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Preface 


Intended Audience 

This manual is intended for system programmers who want to take advantage 
of the time and space savings that result from direct use of I/O devices. 
Users of VMS who do not require such detailed knowledge of I/O drivers can 
use the device-independent services described in the VMS Record Management 
Services Manual. 



Document Structure 

This manual is organized into eight chapters and two appendixes, as follows: 

• Chapter 1 describes the Queue I/O (QIO) interface to file system ancillary 
control processes (ACPs). 

• Chapters 2 through 8 describe the use of VMS file-structured and real¬ 
time I/O device drivers, the drivers for storage devices such as disks and 
magnetic tapes, and terminal devices supported by VMS: 

— Chapter 2 discusses the card reader driver. 

— Chapter 3 discusses disk drivers. 

— Chapter 4 discusses the LPA11-K driver. 

— Chapter 5 discusses the line printer drivers. 

— Chapter 6 discusses the magnetic tape drivers. 

— Chapter 7 discusses the mailbox driver. 

— Chapter 8 discusses the terminal driver. 

• Appendix A summarizes the QIO function codes, arguments, and function 
modifiers used by the drivers listed above. 

• Appendix B lists the DEC Multinational Character Set and the ANSI and 
DIGITAL-private escape sequences for terminals. 


Associated Documents 

The following documents provide additional information: 

• VMS System Services Reference Manual 

• VMS Software Information Management Handbook 

• VMS Software VMS System Software Handbook 

• Guide to VMS Programming Resources 

• VMS Record Management Services Manual 

• LPA11-K laboratory Peripheral Accelerator User's Guide 
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• VMS Networking Manual 

• VMS System Messages and Recovery Procedures Reference Volume 

• VMS Device Support Manual 

Conventions 


Convention Meaning 

In examples, a key name (usually abbreviated) 
shown within a box indicates that you press 
a key on the keyboard; in text, a key name is 
not enclosed in a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key is not usually shown in syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 

A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 
box. 

$ SHOW TIME In examples, system output (what the system 

05-JUN-1988 11:55:22 displays) is shown in black. User input (what 

you enter) is shown in red. 

$ TYPE MYFILE.DAT In examples, a vertical series of periods, or 

ellipsis, means either that not all the data that 
the system would display in response to a 
command is shown or that not all the data a 
user would enter is shown. 

input-file, ... In examples, a horizontal ellipsis indicates 

that additional parameters, values, or other 
information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 

[logical-name] Brackets indicate that the enclosed item is 

optional. (Brackets are not, however, optional 
in the syntax of a directory name in a file 
specification or in the syntax of a substring 
specification in an assignment statement.) 


CTRL/C 


xx 








Preface 


The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 

Hyphens in coding examples indicate that 
additional arguments to the request are provided 
on the line that follows. For example: 

CMDOFAB: $FAB fac=put,fnm=sys$output:,- 
mrs=132,rat=cr,rfm=var 
CMDORAB: $RAB ubf=cmdbuf,usz=cmdbsz,- 
fab=cmdofab 

Unless otherwise noted, all numbers in the 
text are assumed to be decimal. Nondecimal 
radixes—binary, octal, or hexadecimal—are 
explicitly indicated in the coding examples. 



quotation marks 
apostrophes 


numbers 
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New and Changed Features 


This revision of the VMS I/O User's Reference Manual: Part I reflects the 
technical changes since VMS Version 4.4. The following chapters contain 
new or changed information: 

• Chapter 1 

- Sections 1.3.1.3 and 1.6.1.3 describe directory entry protection and 
creation. 





Chapter 2 

- Section 2.2.1.2 describes the methods you use to change the 
translation mode. 

- Section 2.2.2 describes how you submit batch jobs through the card 
reader. 





Chapter 3 

- Table 3-1 includes the new disk devices supported for V5.0. 

- Section 3.2.1.2.1 describes a restriction on dual-ported non-DSA disks 
in a VAXcluster. 

- Section 3.2.7 provides information on the VAXstation 2000/MicroVAX 
2000 disk driver. 

Chapter 6 

- Section 6.4 provides an example of how to correctly define the PI 
parameter in a IO$_SKIPRECORD QIO. 

- Table 6-1 includes the new magnetic tape devices supported for 
V5.0. 






Chapter 8 

- Section 8.4.3 describes the consequences if you use 
TT2$V_FALLBACK for a disconnected virtual terminal (_VTAx:) or if 
the Terminal Fallback Facility is not activated. 

- Section 8.4.4 describes the LAT port driver QIO interface. 
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ACP—QIO Interface 


An ancillary control process (ACP) is a process that interfaces between the 
user process and the driver, and perforins functions that supplement the 
driver's functions. Virtual I/O operations involving file-structured devices 
(disks and magnetic tapes) often require ACP intervention. In most cases, 
ACP intervention is requested by VMS Record Management Services (RMS) 
and is transparent to the user process. However, user processes can request 
ACP functions directly by issuing a QIO request and specifying an ACP 
function code, as shown in Figure 1-1. 

Executing physical and logical I/O operations on a device being managed 
by a file ACP will interfere with the operation of the ACP and will result in 
unpredictable consequences, including system failure in certain cases. 

In addition to the ACP, the VMS operating system also provides the XQP 
(extended QIO processor) facility to supplement the QIO driver's functions 
when performing virtual I/O operations on file-structured devices (ACP for 
Files-11 On-Disk Structure Level 1 and XQP for Files-11 On-Disk Structure 
Level 2). However, rather than being a separate process, the XQP executes as 
a kernel mode thread in the process of its caller. 

This chapter describes the QIO interface to ACPs for disk and magnetic tape 
devices (file system ACPs). The sample program in Chapter 6 performs QIO 
operations to the magnetic tape ACP. 

Figure 1-1 ACP-QIO Interface 
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This section also describes a number of structures and field names of the 
form xxx$name. A VAX MACRO program can define symbols of this form by 
invoking the $xxxDEF macro. 


The following macros are available in SYS$LIBRARY:STARLET.MLB: 

$IODEF 

$FIBDEF 

$ATRDEF 

$SBKDEF 
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The following macros are available in SYS$LIBRARY:LIB.MLB: 

SFATDEF 

$DQFDEF 

$FCHDEF 

Programs written in BLISS-32 can use these symbols by referencing them and 
including the correct library, SYS$LIBRARY:STARLET.L32 (for the macros 
listed under SYS$LIBRARY:STARLET.MLB), and SYS$LIBRARY:LIB.L32 (for 
the macros listed under SYS$LIBRARY:LIB.MLB). 

References to ANSI refer to the American National Standard Magnetic Tape 
Labels and File Structures for Information Interchange, ANSI X3. 27-1978. 


1.1 ACP Functions and Encoding 

All VMS ACP functions can be expressed using seven function codes and four 
function modifiers. The function codes are as follows: 

• IO$_CREATE—Creates a directory entry or file 

• IO$_ACCESS—Searches a directory for a specified file and accesses the 
file, if found 

• IO$_DEACCESS—Deaccesses a file and, if specified, writes the final 
attributes in the file header 

• IO$_MODIFY—Modifies the file attributes and file allocation 

• IO$_DELETE—Deletes a directory entry and file header 

• IO$_MOUNT—Informs the ACP when a volume is mounted; requires 
MOUNT privilege 

• IO$—ACPCONTROL—Performs miscellaneous control functions 
The function modifiers are: 

• IO$M—ACCESS—Opens a file on the user's channel 

• IO$M_CREATE—Creates a file 

• IO$M_DELETE—Deletes a file (or marks it for deletion) 

• IO$M_DMOUNT—Dismounts a volume 

In addition to the function codes and modifiers, VMS ACPs take five device- 
or function-dependent arguments, as shown in Figure 1-2. The first 
argument, PI, is the address of the file information block (FIB) descriptor. 
Section 1.2 describes the FIB in detail. 

The second argument, P2, is an optional argument used in directory 
operations. It specifies the address of the descriptor for the file name string to 
be entered in the directory. 

Argument P3 is the address of a word to receive the resultant file name string 
length. The resultant string is not padded. The actual length is returned in 
P3. P4 is the address of a descriptor for a buffer to receive the resultant file 
name string. Both of these arguments are optional. 
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1.1 ACP Functions and Encoding 


Figure 1-2 ACP Device- or Function-Dependent Arguments 


31 ___0 


PI: 

Address of FIB descriptor 

P2: 

Address of file name string descriptor (optional) 

P3: 

Address of word to receive resultant string length (optional) 

P4: 

Address of resultant string descriptor (optional) 

P5: 

Address of attribute control block (optional) 
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The fifth argument, P5, is an optional argument containing the address of the 
attribute control block. Section 1.3.5 describes the attribute control block in 
detail. 

All areas of memory specified by the descriptors must be capable of being 
read or written to. 

Figure 1-3 shows the format for the descriptors. The count field is the length 
in bytes of the item described. 

Figure 1-3 ACP Device/Function Argument Descriptor Format 
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1.2 File Information Block (FIB) 

The file information block (FIB) contains much of the information that is 
exchanged between the user process and the ACP. Figure 1-4 shows the 
format of the FIB. The FIB must be writable. Because the FIB is passed by 
a descriptor (see Figure 1-3), its length can vary. Thus, a short FIB can be 
used in ACP calls that do not need arguments near the end of the FIB. The 
ACP treats the omitted portion of the FIB as if it were 0. Figure 1-5 shows 
the format of a typical short FIB that would be used to open an existing file 
Table 1-1 gives a brief description of each of the FIB fields. More detailed 
descriptions are provided in Sections 1.3 and 1.6. 
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1.2 File Information Block (FIB) 



Figure 1-4 File Information Block Format 


£1_ 24 23 _ 16 15 _ 8 7 0 


FIB$B_WSIZE 

FIB$I_ACCTL 


V—FID 

FIB$W_DID 

riD^v 


FIB$I_WCC 

FIB$W_CNTRLFUNC/FIB$W_EXCTL 

FIB$W_NMCTL 

FIB$I—CNTRLVAL/FIB$L _EXSZ 

FIB$L_EXVBN 


FIB$B_ ALALIGN 

FIB$B_ ALOPTS 

I 

u. 

ALLOC 

reserved 

FIB$W_VERLIMIT 

FIB$I_ACLCTX 

FIB$I_AC!_STATUS 

FIB$I_STATUS 

FIB$I— ACI_ACCESS 
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1.2 File Information Block (FIB) 



Figure 1-5 Typical Short File Information Block 


31 24 23 _ 16 15 _8_7_0 


FIB$B_WSIZE 

FIB$I_ACCTL 





F1 B$W__ F1D 


FIB$W_DID 





FIB$L 

1 

:> 

o 

o 



-— 0 

FIB$W_NMCTL 



0 
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Table 1-1 Contents of the File Information Block 

Field Subfields Meaning 

FIB$I_ACCTL Contains flag bits that control 

the access to the file. Sections 

1.3.1.1, 1.3.2.1, 1.6.1.1, 

1.6.4.1, and 1.6.5 describe the 

FIB$I_ACCTL field flag bits. 

FIB$B_WSIZE Controls the size of the file 

window used to map a disk 
file. If a window size of 255 
is specified, the file is mapped 
completely through the use of 
segmented windows. 

FIB$W_FID Specifies the file identification. 

You supply the file identifier 
when it is known; the ACP 
returns the file identifier when it 
becomes known, for example, 
as a result of a create or 
directory lookup. A 0 file 
identifier can be specified when 
an operation is performed on 
a file that is already open on 
a particular channel. The ACP 
returns the file identifier of 
the open file. The following 
subfields are defined: 

FIB$W_FID_NUM File number. 
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1.2 File Information Block (FIB) 

Table 1—1 (Cont.) Contents of the File Information Block 
Field Subfields Meaning 


FIB$W_FID_SEQ 

FIB$W_FID_RVN 

File sequence number. 

Relative volume number (only for 
magnetic tape devices). 

FIB$B_FID_RVN 

Relative volume number (only for 
disk devices). 

FIB$B_FID_NMX 

File number extension (only for 
disk devices). 

FIB$W_DID 

Contains the file identifier of 
the directory file. The following 
subfields are defined: 

FIB$W_DID_NUM 

FIB$W_DID_SEQ 

FIB$W_DID_RVN 

File number. 

File sequence number. 

Relative volume number (only for 
magnetic tape devices). 

FIB$B_DID_RVN 

Relative volume number (only for 
disk devices). 

FIB$B_DID_NMX 

File number extension (only for 
disk devices). 

FIB$L_WCC 

Maintains position context when 
processing wildcard directory 
operations. 

FIB$W_NMCTL 

Contains flag bits that control 
the processing of a name 
string in a directory operation. 
Sections 1.3.1.1 and 1.6.1.1 
describe the FIB$W_NMCTL 
field flag bits. 

FIB$W_EXCTL 

Contains flag bits that specify 
extend control for disk devices. 
Sections 1.3.3.1 and 1.3.4.1 
describe the FIB$W_EXCTL field 
flag bits. 

FIB$W_CNTRLFUNC 

In an IO$_ACPCONTROL 
function, this field contains 
the code that specifies which 

ACP control function is to be 
performed (see Section 1.6.7). 
This field overlays FIB$W_ 
EXCTL. 

FIB$C_USEREOT 

User EOT mode. In an IO$__ 
CREATE or IO$_ACCESS 
function, you can set this mode 
on a per file basis. (See Sections 
1.6.1 and 1.6.2.) 
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1.2 File Information Block (FIB) 


Table 1-1 (Cont.) Contents of the File Information Block 

Field Subfields Meaning 

FIB$I_EXSZ Specifies the number of blocks 

to be allocated in an extend 
operation on a disk file. 

FIB$I_CNTRLVAL Contains a control function value 

used in an IO$_ACPCONTROL 
function (see Section 1.6.7). 

The interpretation of the 
value depends on the control 
function specified in FIB$W_ 
CNTRLFUNC. This field overlays 
FIB$L_EXSZ. 


FIB$I_EXVBN 

FIB$B_ALOPTS 


FIB$B_ALALIGN 

FIB$W_ALLOC 


Specifies the starting disk file 
virtual block number at which a 
file is to be truncated. 

Contains option bits that control 
the placement of allocated 
blocks. Section 1.3.3.1 
describes the FIB$B_ALOPTS 
field flag bits. 

Contains the interpretation 
mode of the allocation (FIB$W_ 
ALLOC) field. 

Contains the desired physical 
location of the blocks being 
allocated. Interpretation of the 
field is controlled by the FIB$B_ 
ALALIGN field. The following 
subfields are defined: 


FIB$W_LOC_FID 

FIB$W_LOC_NUM 

FIB$W_LOC_SEQ 

FIB$B_LOC_RVN 

FIB$B_LOC_NMX 
FIB$L _LOC_ADDR 

FIB$W_VERLIMIT 
FIB$I_ACLCTX 


Three-word related file ID for RFI 
placement. 

Related file number. 

Related file sequence number. 

Related file RVN or placement 
RVN. 

Related file number extension. 

Placement LBN, cylinder, or 
VBN. 

Contains the version limit of the 
directory entry. 

Maintains position context when 
processing ACL attributes from 
the attribute (P5) list. 
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1.2 File Information Block (FIB) 


Table 1-1 (Cont.) Contents of the File Information Block 


Field 

Subfields 

Meaning 

FIB$L_ACL_ 

STATUS 


Status of the requested ACL 
attribute operation, if any. The 
ACL attributes are included in 
Table 1-7. If no ACL attributes 
are given, SS$_NORMAL is 
returned here. 

FIB$I_STATUS 


Access status. Applies to all 
major functions. The following 
bits are supported: 


FIB$V_ALT_REQ 

Set to indicate whether the 
alternate access bit is required 
for the current operation. If not 
set, the alternate access bit is 
optional. 


FIB$V_ALT_ 

GRANTED 

If FIB$V_ALT_REQ = 0, the FIB 
bit returned from the file system 
is set if the alternate access 
check succeeded. 

FIB$I_ALT- 

ACCESS 


A 32-bit mask that represents 
an access mask to check against 
file protection; for example, 
opens a file for read access 
and checks whether it can be 
deleted. The mask has the same 
configuration as the standard 
protection mask. 


ACP Subfunctions 

The operations that the ACP performs can be organized into two categories: 
major ACP functions and subfunctions. Each ACP operation performs one 
major function. That function is specified by an I/O function code, such 
as IO$_ACCESS, IO$_CREATE, or IO$_MODIFY. While executing the 
major function, one or more subfunctions can be performed. A subfunction 
is an operation such as looking up, accessing, or extending a file. Most 
subfunctions can be executed by more than one of the major functions. 
Sections 1.3.1 through 1.3.5 describe the following subfunctions in detail: 

• Directory Lookup 

• Access 

• Extend 

• Truncate 

• Read Attributes 

• Write Attributes 

Section 1.6, which contains the descriptions of the major functions, lists the 
subfunctions available to each major function. 
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1.3 ACP Subfunctions 


1.3.1 Directory Lookup 

The directory lookup subfunction is used to search for a file in a disk directory 
or on a magnetic tape. This subfunction can be invoked using the major 
functions IO$_ACCESS ; IO$_MODIFY, IO$_DELETE, and 
IO$_ACPCONTROL. A directory lookup occurs if the directory file ID field 
in the FIB (FIB$W_DID) is a nonzero number. 


1.3.1.1 Input Parameters 

Table 1-2 lists the FIB fields that control the processing of a lookup 
subfunction. 


Table 1-2 FIB Fields (Lookup Control) 


Field 

Field Values 

Meaning 

FIB$W_NMCTL 


Name string control. The following 
name control bits are applicable to 
a lookup operation: 


FIB$M_WILD 

Set if name string contains 
wildcards. Setting this bit causes 
wildcard context to be returned in 
FIB$L_WCC. 


FIB$M_ALLNAM 

Set to match all name field values. 


FIB$M_ALLTYP 

Set to match all field type values. 


FIB$M_ALLVER 

Set to match all version field 
values. 


FIB$M_FINDFID 

Set to search a directory for the file 
identifier in FIB$W_FID. 

FIB$W_FID 


File identification. The file ID of the 
file found is returned in this field. 

FIB$W_DID 


Contains the file identifier of the 
directory file. This field must be a 
nonzero number. 

FIB$L_WCC 


Maintains position context when 
processing wildcard directory 
operations. 

FIB$I_ACCTL 


The following access control flag is 
applicable to a lookup subfunction: 


FIB$M_REWIND 

Set to rewind magnetic tape before 
lookup. If not set, a magnetic 
tape is searched from its current 
position. 


QIO arguments P2 through P6 are passed as values. The second argument, 
P2, specifies the address of the descriptor for the file name string to be 
searched for in the directory. 

The file name string must have one of the following two formats: 

name.type;version 

name.type.version 
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1.3 ACP Subfunctions 


The name and type can be any combination of alphanumeric characters, and 
the dollar sign ($), asterisk (*), and percent (%) characters. The version 
must consist of numeric characters optionally preceded by a minus sign (-) 
(only for disk devices) or a single asterisk. The total number of alphanumeric 
and percent characters in the name field and in the type field must not exceed 
39. Any number of additional asterisks can be present. 

If any of the bits FIB$M_ALLNAM, FIB$M_ALLTYP, and FIB$M_ALLVER 
are set, then the contents of the corresponding field in the name string are 
ignored and the contents are assumed to be an asterisk. 

Note that the file name string cannot contain a directory string. The directory 
is specified by the FIB$W_DID field (see Table 1-1). Only VMS RMS can 
process directory strings. 

Argument P3 is the address of a word to receive the resultant file name string 
length. 

Argument P4 is the address of a descriptor for a buffer to receive the 
resultant file name string. The resultant string is not padded. The P3 and 
P4 arguments are optional. 


1.3.1.2 Operation 

The system searches either the directory file specified by FIB$W_DID or 
the magnetic tape for the file name specified in the P2 file name parameter. 
The actual file name found and its length are returned in the P3 and P4 
length and result string buffers. The file ID of the file found is returned in 
FIB$W_FID and can be used in subsequent operations as the major function 
is processed. 

Zero and negative version numbers have special significance in a disk lookup 
operation. Specifying 0 as a version number causes the latest version of the 
file to be found. Specifying -1 locates the second most recent version, -2 the 
third most recent, and so forth. Specifying a version of -0 locates the lowest 
numbered version of the file. For magnetic tape lookups, a version number 
of 0 locates the first occurrence of the file encountered; negative version 
numbers are not allowed. 

Wildcard lookups are performed by specifying the appropriate wildcard 
characters in the name string and setting FIB$M_WILD. (The name control 
bits FIB$M_ALLNAM, FIB$M_ALLTYP, and FIB$M_ALLVER can also be 
used in searching for wildcard entries, but they are intended primarily for 
compatibility mode use.) On the first lookup, FIB$L_WCC should contain 
zero entries. On each lookup, the ACP returns a nonzero value in 
FIB$L_WCC, which must be passed back on the next lookup call. In 
addition, you must pass the resultant name string returned by the previous 
lookup using the P4 result string buffer, and its length in the P3 result length 
word. This string is used together with FIB$L_WCC to continue the wildcard 
search at the correct position in the directory. 

Perform a lookup by file ID by setting the name control bit FIB$M_FINDFID. 
When this bit is set, the system searches the directory for an entry containing 
the file ID specified in FIB$W_FID, and the name of the entry found is 
returned in the P3 and P4 result parameters. Note that if a directory contains 
multiple entries with the same file ID, only the first entry can be located with 
this technique. 

Lookups by file ID should be done only when the file name is not available, 
because lookups by this method are often significantly slower than lookups 
by file name. 
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1.3 ACP Subfunctions 


1.3.1.3 Directory Entry Protection 

A directory entry is protected with the same protection code as the file itself. 
For example, if a file is protected against delete access, then the file name 
has the same protection. Consequently, a nonprivileged user (that is, a user 
who is not the volume owner or a user who does not have SYSPRV) cannot 
rename a file because renaming a file is essentially the same as deleting 
the file name. This protection is applied regardless of the protection on the 
directory file. 

Nonprivileged users can neither write directly into a .DIR;1 directory file nor 
turn off the directory bit in a directory file header. 


1,3.2 Access 


The access subfunction is used to open a file so that virtual read or write 
operations can be performed. This subfunction can be invoked using the 
major functions IO$_CREATE and IO$—ACCESS (see Sections 1.6.1 and 
1.6.2). An access subfunction is performed if the IO$M__ACCESS modifier is 
specified in the I/O function code. 


1.3.2.1 


Input Parameters 

Table 1-3 lists the FIB fields that control the processing of an access 
subfunction. 

Table 1-3 FIB Fields (Access Control) 

Field Field Values Meaning 


FIB$I_ACCTL 

FIB$M_WRITE 

FIB$M_NOREAD 

FIB$M_NOWRITE 

FIB$M_NOTRUNC 

FIB$M_DLOCK 


Specifies field values that control 
access to the file. The following 
access control bits are applicable 
to the access subfunction: 

Set for write access; clear for 
read-only access. 

Set to deny read access to others. 
(You must have write privilege to 
the file to use this option.) 

Set to deny write access to others. 

Set to prevent the file from being 
truncated; clear to allow truncation. 

Set to enable deaccess lock (close 
check). Used only for disk devices. 

Used to flag a file as inconsistent 
if the program currently modifying 
the file terminates abnormally. 

If the program deaccesses the 
file without performing a write 
attributes operation, the file is 
marked as locked and cannot be 
accessed until it is unlocked. 
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1.3 ACP Subfunctions 


Table 1-3 (Cont.) FIB Fields (Access Control) 


Field 

Field Values 

Meaning 


FIB$M_UPDATE 

Set to position at start of a 
magnetic tape file when opening 
file for write; clear to position at 
end-of-file. 


FIB$M_READCK 

Set to enable read checking of 
the file. Virtual reads to the file 
are performed using a data check 
operation. 


FIB$M_WRITECK 

Set to enable write checking of 
the file. Virtual writes to the file 
are performed using a data check 
operation. 


FIB$M_EXECUTE 

Set to access the file in execute 
mode. The protection check is 
made against the EXECUTE bit 
instead of the READ bit. Valid 
only for requests issued from 
SUPERVISOR, EXEC, or KERNEL 
mode. 


FIB$M_NOLOCK 

Set to override exclusive access 
to the file, allowing you to access 
the file when another user has the 
file open with FIB$M_NOREAD 
specified. You must have SYSPRV 
privilege or ownership of the 
volume to use this option. FIB$M_ 
NOREAD and FIB$M_NOWRITE 
must be clear for this option to 
work. 


FIB$M_NORECORD 

Set to inhibit recording of the file's 
expiration date. If not set, the file's 
expiration date can be modified, 
depending on the file retention 
parameters of the volume. 

FIB$B_WSIZE 


Controls the size of the file window 
used to map a disk file. The ACP 
uses the volume default if FIB$B_ 
WSIZE is 0. A value of 1 to 127 
indicates the number of retrieval 
pointers to be allocated to the 
window. A value of -1 indicates 
that the window should be as large 
as necessary to map the entire file. 
Note that the window is charged to 
the user's BYTELIM quota. 

FIB$W_FID 


Specifies the file identification of 
the file to be accessed. 
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1.3.2.2 Operation 

The file is opened according to the access control specified (see Table 1-3). 


1.3.3 Extend 


The extend subfunction is used to allocate space to a disk file. This 
subfunction can be invoked using the major I/O functions IO$_CREATE 
and IO$_MODIFY (see Sections 1.6.1 and 1.6.4). The extend subfunction 
is performed if the bit FIB$M__EXTEND is set in the extend control word 
FIB$W_EXCTL. 


1.3.3.1 






Input Parameters 

Table 1-4 lists the FIB fields that control the processing of an extend 
subfunction. 


Table 1-4 FIB Fields (Extend Control) 

Field Field Values Meaning 

FIB$W_EXCTL Extend control flags. The following 

flags are applicable to the extend 
subfunction: 


FIB$L_EXSZ 


FIB$M_EXTEND Set to enable extension. 

FIB$M_NOHDREXT Set to inhibit generation of 
extension file headers. 


FIB$M_ALCON Allocates contiguous space. 

The extend operation fails if the 
necessary contiguous space is not 
available. 


FIB$M_ALCONB Allocates the maximum amount of 
contiguous space. 

If both FIB$M_ALCON and 
FIB$M_ALCONB are set, a single 
contiguous area, whose size is 
the largest available but not 
greater than the size requested, 
is allocated. 


FIB$M_FILCON Marks the file contiguous. This bit 

can only be set if the file does not 
have space already allocated to it. 

FIB$M_ALDEF Allocates the extend size (FIB$I— 

EXSZ) or the system default, 
whichever is greater. 

Specifies the number of blocks to 
allocate to the file. 
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Table 1-4 (Cont.) FIB Fields (Extend Control) 

Field Field Values Meaning 


FIB$I_EXVBN 

FIB$B_ALOPTS 

FIB$M_EXACT 

FIB$M_ONCYL 

FIB$B_ALALIGN 

(zero) 

FIB$C_CYL 

FIBSC—LBN 

FIB$C_VBN 


The number of blocks actually 
allocated for this operation 
is returned in this longword. 

More blocks than requested 
can be allocated to meet cluster 
boundaries. 

Returns the starting virtual block 
number of the blocks allocated. 

FIB$I_EXVBN must initially contain 

0 blocks. 

Contains option bits that control 
the placement of allocated blocks. 
The following bits are defined: 

Set to require exact placement; 
clear to specify approximate 
placement. If this bit is set and the 
specified blocks are not available, 
the extend operation fails. 

Set to locate allocated space within 
a cylinder. This option functions 
correctly only when FIB$M_ALCON 
or FIB$M_ALCONB is specified. 

Contains the interpretation mode 
of the allocation (FIB$W_ALLOC) 
field. One of the following values 
can be specified: 

No placement data. The remainder 
of the allocation field is ignored. 

Location is specified as a byte 
relative volume number (RVN) in 
FIB$B_LOC_RVN and a cylinder 
number in FIB$I_LOC—ADDR. 

Location is specified as a byte RVN 
in FIB$B_LOC_RVN, followed by 
a longword logical block number 
(LBN) in FI B$ L _LOC_ A DDR. 

Location is specified as a longword 
virtual block number (VBN) of the 

file being extended in FIB$I_LOC_ 

ADDR. A 0 VBN or one that fails to 
map indicates the end of the file. 
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Table 1-4 (Cont.) FIB Fields (Extend Control) 


Field 

Field Values 

Meaning 


FIB$C_RFI 

Location is specified as a three- 
word file ID in FIB$W_LOC_FID, 
followed by a longword VBN of 

that file in FIB$I_LOC—ADDR. A 

0 file ID indicates the file being 
extended. A 0 VBN or one that 
fails to map indicates the end of 
that file. 

FIB$W_ALLOC 


Contains the desired physical 
location of the blocks being 
allocated. Interpretation of the 
field is controlled by the FIB$B_ 
ALALIGN field. The following 
subfields are defined: 


FIB$W_LOC_FID 

Three-word related file ID for RFI 
placement. 


FIB$W_LOC_NUM 

Related file number. 


FIB$W_LOC_SEQ 

Related file sequence number. 


FIB$B_LOC_RVN 

Related file RVN or placement RVN. 


FIB$B_LOC_NMX 

Related file number extension. 


FIB$I_LOC—ADDR 

Placement LBN, cylinder, or VBN. 


1.3.3.2 Operation 

The specified number of blocks are allocated and appended to the file. The 
virtual block number assigned to the first block allocated is returned in 
FIB$L_EXVBN. The actual number of blocks allocated is returned in 
FIB$L_EXSZ. 

The actual number of blocks allocated is also returned in the second longword 
of the user's I/O status block. If a contiguous allocation (FIB$M_ALCON) 
fails, the size of the largest contiguous space available on the disk is returned 
in the second longword of the user's I/O status block. 


1.3.4 Truncate 

The truncate subfunction is used to remove space from a disk file. This 
subfunction can be invoked by the major I/O functions IO$_DEACCESS 
and IO$_MODIFY (see Sections 1.6.3 and 1.6.4). The truncate subfunction 
is performed if the bit FIB$M—TRUNCATE is set in the extend control word 
FIB$W_EXCTL. 
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1.3.4.1 


Input Parameters 

Table 1-5 lists the FIB fields that control the processing of a truncate 
subfunction. 


Table 1-5 FIB Fields (Truncate Control) 


Field 

Field Values 

Meaning 

FIB$W_EXCTL 


Extend control flags. The following 
flags are applicable to the truncate 
subfunction: 


FIB$M_TRUNC 

Must be set to enable truncation. 


FIB$M_MARKBAD 

Set to append the truncated blocks 
to the bad block file, instead of 
returning them to the free storage 
pool. Only one cluster can be 
deallocated. This is most easily 
accomplished by specifying the last 

VBN of the file in FIB$I_EXVBN. 

SYSPRV privilege or ownership of 
the volume is required to deallocate 
blocks to the bad block file. 

FIB$L_EXSZ 


Returns the actual number of 

blocks deallocated. FIB$I_EXSZ 

must initially contain a value of 0. 

FIB$I_EXVBN 


Specifies the first virtual block 
number to be removed from the 
file. The actual starting virtual block 
number of the truncate operation is 
returned in this field. 


1.3.4.2 Operation 

Blocks are deallocated from the file, starting with the virtual block specified 
in FIB$L_EXVBN and continuing through the end of the file. The actual 
number of blocks deallocated is returned in FIB$L _EXSZ. The virtual block 
number of the first block actually deallocated is returned in FIB$L_EXVBN. 
Because of cluster round-up, this value might be greater than the value 
specified. If FIB$M_MARKBAD is specified, the truncation VBN is rounded 
down instead of up, and the value returned in FIB$L_EXVBN might be less 
than that specified. 

The number of blocks by which FIB$L_EXVBN was rounded up is returned 
in the second longword of the I/O status block. 

The truncate subfunction normally requires exclusive access to the file at run 
time. This means, for example, that a file cannot be truncated while multiple 
writers have access to it. 

An exception occurs when a truncate subfunction is requested for a write- 
accessed file that allows other readers. Although the truncate subfunction 
returns success status in this instance, the actual file truncation (the return of 
the truncated blocks to free storage) is deferred until the last reader deaccesses 
the file. If a new writer accesses the file after the truncate subfunction is 
requested, but before the last deaccess, the deferred truncation is ignored. 
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1.3.5 Read/Write Attributes 

The read and write attributes subfunctions are used for operations such as 
reading and writing file protection and creating and revising dates. A read or 
write attributes operation is invoked by specifying an attribute list with the 
QIO parameter P5. A read attributes operation can be invoked by the major 
I/O function IO$_ACCESS (see Section 1.6.2); a write attributes operation 
can be invoked by the major I/O functions IO$_CREATE, IO$_DEACCESS, 
and IO$_MODIFY (see Sections 1.6.1, 1.6.3, and 1.6.4). 


1.3.5.1 Input Parameters 

The read or write attributes subfunction is controlled by the attribute list 
specified by P5. The list consists of a variable number of two longword 
control blocks, terminated by a 0 longword, as shown in Figure 1-6. The 
maximum number of attribute control blocks in one list is 30. Table 1-6 
describes the attribute control block fields. 

Figure 1-6 Attribute Control Block Format 


31 16 15 0 


ATR$W_TYPE 

ATR$W_SIZE 



ATR$L. 

_ADDR 



(additional control blocks) ? 

0 


ZK-640-82 


Table 1-6 Attribute Control Block Fields 

Field Meaning 

ATR$W_SIZE Specifies the number of bytes of the attribute to be 

transferred. Legal values are from 0 to the maximum size 
of the particular attribute (see Table 1-7). 

ATR$W_TYPE Identifies the individual attribute to be read or written. 

ATR$L_ADDR Contains the buffer address of the memory space to or 

from which the attribute is to be transferred. The attribute 
buffer must be writable. 


Table 1-7 lists the valid attributes for ACP-QIO functions. The maximum 
size (in bytes) is determined by the required attribute configuration. For 
example, the Radix-50 file name (ATR$S_FILNAM) uses only 6 bytes, but it 
is always accompanied by the file type and file version, so a total of 10 bytes 


1-17 























ACP—QIO Interface 

1.3 ACP Subfunctions 


is required. Each attribute has two names: one for the code (for example, 
ATR$C_UCHAR) and one for the size (for example, ATR$S_UCHAR). 


Table 1-7 ACP—QIO Attributes 


Attribute Name 1 

Maximum 

Size 

(bytes) 

Meaning 

ATR$C_UCHAR 2 4 

4 

4-byte file characteristics. (The 
file characteristics bits are listed 
following this table.) 

ATR$C_RECATTR 3 

32 

Record attribute area. Section 1.4 
describes the record attribute area 
in detail. 

ATR$C_FILNAM 

10 

6-byte Radix-50 file name plus 
ATR$C_FILTYP and ATR$C_ 
FILVER. 

ATR$C_FILTYP 

4 

2-byte Radix-50 file type plus 
ATR$C_FILVER. 

ATR$C_FILVER 

2 

2-byte binary version number. 

ATR$C_EXPDAT 2 

7 

Expiration date in ASCII. Format: 
DDMMMYY. 

ATR$C_ST ATBLK 5 

32 

Statistics block. Section 1.5 
describes the statistics block in 
detail. 

ATR$C_HEADER 5 

512 

Complete file header. 

ATR$C_BLOCKSIZE 

2 

Magnetic tape block size. 

ATR$C_USERLABEL 6 

80 

User file label. 

ATR$C_ASCDATES 2 4 

35 

Revision count (2 binary bytes), 
revision date, creation date, 
and expiration date, in ASCII. 
Format: DDMMMYY (revision 
date), HHMMSS (time), DDMMMYY 
(creation date), HHMMSS (time), 
DDMMMYY (expiration date). (The 
format contains no embedded 
spaces or commas.) 

ATR$C_ALCONTROL 

14 

Compatibility mode allocation data. 

ATR$C_ENDLBLAST 

4 

End of magnetic tape label 
processing; provides AST control 
block. 


Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the 
code and one with an ATR$S_ prefix for the size, which is not included in the list. 


Protected (can be written to only by system or owner). 

3 Locked (cannot be written to while the file is locked against writers). 

4 Not supported on write operations to MTAACP; defaults are returned on read operations. 
5 Read only. 

6 Not supported for disk devices. 
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Table 1-7 (Cont.) ACP—QIO Attributes 

Maximum 

Size 

Attribute Name 1 (bytes) Meaning 


ATR$C_ASCNAME 20 


ATR$C_CREDATE 2 8 

ATR$C_REVDATE 2 3 8 

ATR$C_EXPDATE 2 8 

ATR$C_BAKDATE 3 10 8 

ATR$C_UIC 2 4 

ATR$C_FPR0 2 3 2 

ATR$C_RPR0 10 2 

ATR$C_ACLEVEL 2 3 10 1 

ATR$C_SEMASK 10 8 

ATR$C_UIC_R0 5 4 

ATR$C_DIRSEQ 10 2 

ATR$C_B ACKLINK 10 6 

ATR$C_JOURNAL 10 2 

ATR$C_HDR 1 _ACC 1 


ATR$C_ADDACLENT 7 10 11 255 

ATR$C_DELACLENT 7 10 11 255 

ATR$C_MODACLENT 7 10 11 255 

ATR$C_FNDACLENT 10 11 255 


Disk: file name, type, and version, 
in ASCII, including punctuation. 
Format: name.type;version. 

Magnetic tape: contains 17- 
character file identifier (ANSI a); 
no version number. Overrides 
all other file name and file type 
specifications if supplied on input 
operations. If specified on an 
access operation and you want 
only a value to be returned, specify 
(in ATR$W_SIZE) a buffer of 
greater than 17 bytes. 

64-bit creation date and time. 
64-bit revision date and time. 

64-bit expiration date and time. 
64-bit backup date and time. 

4-byte file owner UIC. 

File protection. 

2-byte record protection. 

File access level. 

File security mask and limit. 

4-byte file owner UIC. 

Directory update sequence count. 
File back link pointer. 

Journal control flags. 

ANSI magnetic tape header label 
accessibility character. 

Add one or more access control 
entries. 

Remove an access control entry. 
Modify an ACL entry. 

Locate an ACL entry. 


I Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the 
code and one with an ATR$S_ prefix for the size, which is not included in the list. 

2 Protected (can be written to only by system or owner). 

3 Locked (cannot be written to while the file is locked against writers). 

5 Read only. 

Exclusive access required. This operation does not complete successfully if other readers 
or writers are allowed. 

10 Not supported for Files-11 On-Disk Structure Level 1 or magnetic tapes. 

II The status from this attribute operation is returned in FIBSI—ACI—STATUS. 
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Table 1-7 (Cont.) ACP—QIO Attributes 


Attribute Name 1 

Maximum 

Size 

(bytes) 

Meaning 

ATR$C_FNDACETYP 10 11 

255 

Find a specific type of ACE. 

ATR$C_DELETEACL 7 10 11 

255 

Delete the entire ACL. 

ATR$C_READACL 10 11 

512 

Read the entire ACL or as much as 
will fit in the supplied buffer. Only 
complete ACEs are transferred. 
Thus, the supplied buffer can not 
be completely filled. 

ATR$C_ACLLENGTH 10 11 

4 

Return the length of the ACL. 

ATR$C_READACE 10 11 

255 

Read a single ACE. 

ATR$C_RESERVED 9 10 

380 

Modify reserve area. 

ATR$C_HIGHWATER 10 

4 

High-water mark (user read-only). 

ATR$C_PRIVS_USED 8 10 

4 

Privileges used to gain access. 

ATR$C_MATCHING_ACE 8 10 

255 

ACE used to gain access (if any). 

ATR$C_ACCESS_MODE 

1 

Access mode for following attribute 
descriptors. 

ATR$C_FILE_SPEC 10 

512 

Convert FID to file specification. 

ATR$C_BUFFER_0FFSET 4 

2 

Offset length for ANSI magnetic 
tape header label buffer. 


Attributes with an ATR$C_ prefix have two names: one with the ATR$C_ prefix for the 
code and one with an ATR$S_ prefix for the size, which is not included in the list. 


4 Not supported on write operations to MTAACP; defaults are returned on read operations. 

7 Exclusive access required. This operation does not complete successfully if other readers 
or writers are allowed. 

8 This attribute can only be retrieved on the initial file access or create operation. 

9 The actual length available can decrease if the file is extended in a noncontiguous manner 
or if an ACL is applied to the file. 

10 Not supported for Files-11 On-Disk Structure Level 1 or magnetic tapes. 

11 The status from this attribute operation is returned in FIB$I_ACI_STATUS. 


Table 1-8 lists the bits contained in the file characteristics longword, which is 
read with the ATR$C_UCHAR attribute. 
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Table 1-8 File Characteristics Bits 


FCHNOBACKUP 

File is not to be backed up. 

FCH$M_READCHECK 

Verify all read operations. 

FCH$M_WRITCHECK 

Verify all write operations. 

FCH$M_CONTIGB 

Keep file as contiguous as possible. 

FCH$M_LOCKED 

File is deaccess-locked. 

FCH$M _CONTIG 

File is contiguous. 

FCH$M_BADACL 

File's ACL is corrupt. 

FCH$M—SPOOL 

File is an intermediate spool file. 

FCH$M_DIRECTORY 

File is a directory. 

FCH$M_BADBLOCK 

File contains bad blocks. 

FCH$M_MARKDEL 

File is marked for deletion. 

FCH$M_ERASE 

Erase file contents before deletion. 


1.4 ACP QIO Record Attributes Area 

Figure 1-7 shows the format of the record attributes area. 

Figure 1-7 ACP—QIO Record Attributes Area 

31 24 23 16 15 8 7 0 


4 

8 

12 

16 

20 

24 

28 


FAT$W_RSIZE 

FAT$B_RATTRIB 

FAT$B_RTYPE * 

FAT$I_HIBLK 

FAT$I_EFBLK 

FAT$B_VFCSIZE 

FAT$B_BKTSIZE 

FAT$W_FFBYTE 

FAT$W_DEFEXT 

FAT$W_MAXREC 


FAT$W_GBC 

(6 bytes reserved for future use) 

FAT$W_VERSIONS 

not used 


*FAT$V_RTYPE bits 0-3; FAT$V_FILEORG bits 4-7 


ZK-641-82 
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Table 1-9 lists the record attributes values and their meanings. 


Table 1-9 ACP Record Attributes Values 


Field Value 

Meaning 


FAT$B_RTYPE 

Record type. Contains FAT$V_RTYPE and 


FAT$V_FILEORG. 


FAT$V_RTYPE 

Record type. The following bit values are defined: 


FAT$C_FIXED 

Fixed-length record 


FAT$C_VARIABLE 

Variable-length record 


FAT$C_VFC 

Variable-length record with fixed 
control 


FAT$C_UNDEFINED 

Undefined record format (stream 
binary) 


FAT$C_STREAM 

RMS stream format 


FAT$C_STREAMLF 

Stream terminated by LF 


FAT$C_STREAMCR 

Stream terminated by CR 

FAT$V_FILEORG 

File organization. The following bit values are defined: 


FAT$C_DIRECT 

Direct file organization 1 


FAT$C_INDEXED 

Indexed file organization 


FAT$C_RELATIVE 

Relative file organization 


FAT$C_ 

SEQUENTIAL 

Sequential file organization 

FAT$B_RATTRIB 

Record attributes. The 

following bit values are defined: 


FAT$M_ 

FORTRANCC 

FORTRAN carriage control 


FAT$M_IMPLIEDCC 

Implied carriage control 


FAT$M_PRINTCC 

Print file carriage control 


FAT$M_NOSPAN 

No spanned records 

FAT$W_RSIZE 

Record size in bytes. 


FAT$I_HIBLK 2 

Highest allocated VBN. 

The ACP maintains this field when 


the file is extended or truncated. Attempts to modify this 
field in a write attributes operation are ignored. 


FAT$W_HIBLKH 

High-order 16 bits 


FAT$W_HIBLKL 

Low-order 16 bits 

FAT$I_EFBLK 23 

End-of-file VBN 
FAT$W_EFBLKH 

High-order 16 bits 


FAT$W_EFBLKL 

Low-order 16 bits 

FAT$W_FFBYTE 3 

First free byte in FAT$L_EFBLK. 

FAT$B_BKTSIZE 

Bucket size in blocks. 



defined but not implemented. 

inverted format field. The high- and low-order 16 bits are transposed for compatibility 
with PDP-11 software. 

3 When the end-of-file position corresponds to a block boundary, by convention 
FAT$L_EFBLK contains the end-of-file VBN plus 1, and FAT$W_FFBYTE contains 0. 
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© 


Table 1-9 (Cont.) 

ACP Record Attributes Values 

Field Value 

Meaning 

FAT$B_VFCSIZE 

FAT$W_MAXREC 

FAT$W_DEFEXT 

FAT$W_GBC 

FAT$W_VERSIONS 

Size in bytes of fixed-length control for VFC records. 
Maximum record size in bytes. 

Default extend quantity. 

Global buffer count. 

Default version limit; valid only if the file is a directory. 



ACP-QIO Attributes Statistics Block 

Figure 1-8 shows the format of the attributes statistics block. Table 1-10 lists 
the contents of this block. 

Figure 1-8 ACP-QIO Attributes Statistics Block 


31 16 15 8 7 0 



SBK$I_STLBN 

SBK$I_FILESIZE 


SBK$I_FCB 

SBK$B_LCNT 

SBK$B_ACNT 


(not used) 



SBK$W_LCNT 

SBK$W_ACNT 

SBK$W_TCNT 

SBK$W_WCNT 

SBK$I_READS 

SBK$I_WRITES 
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Table 1-10 Contents of the Statistics Block 


Field 

Field Values 

Meaning 

SBK$I_STLBN 


Contains the starting LBN of the file 
if the file is contiguous. If the file is 
not contiguous, this field contains 
a value of 0. The LBN appears as 
an inverted longword (the high- and 
low-order 16 bits are transposed 
for PDP-11 compatibility). The 
following subfields are defined: 


SBKSW—STLBNH 

Starting LBN (high-order 16 bits). 


SBK$W_STLBNL 

Starting LBN (low-order 16 bits). 

SBK$L_FILESIZE 


Contains the size of the file in 
blocks. The file size appears as an 
inverted longword (the high- and 
low-order 16 bits are transposed 
for PDP-11 compatibility). The 
following subfields are defined: 


SBKSW—FILESIZH 

File size (high-order 16 bits). 


SBKSW-FILESIZL 

File size (low-order 16 bits). 

SBKSB-ACNT 1 


Access count (low byte). This 
field is present for PDP-11 
compatibility. 

SBKSB-LCNT 1 


Lock count (low byte). This field is 
present for PDP-11 compatibility. 

SBKSl_FCB 


System pool address of the file's 
file control block. 

SBKSW-ACNT 1 


Access count (the number of 
channels that currently have the file 
open). 

SBKSW—LCNT 1 


Lock count (the number of access 
operations that have locked the file 
against writers). 

SBKSW—WCNT 1 


Writer count (the number of 
channels that currently have the 
file open for write). 

SBKSW-TCNT 1 


Truncate lock count (the number of 
access operations that have locked 
the file against truncation). 

SBKSL-READS 


The number of read operations 
executed for the file on this 
channel. 

SBKSL-WRITES 


The number of write operations 
executed for the file on this 
channel. 

Accesses from processes on the local node in 

a cluster are counted. 
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1.6 Major Functions 

The following sections describe the operation of the major ACP functions. 
Each section describes the required and optional parameters for a particular 
function, as well as the sequence in which the function is performed. For 
clarity, when a major function invokes a subfunction, the input parameters 
used by the subfunction are omitted. 


1.6.1 Create File 

Create file is a virtual I/O function that creates a directory entry or a file on a 
disk device, or a file on a magnetic tape device. 

The following is the function code: 

• IO$_CREATE 

The following are the function modifiers: 

• IO$M__CREATE—Creates a file. 

• IO$M_ACCESS—Opens the file on your channel. 

• IO$M—DELETE—Marks the file for deletion (applicable only to disk 
devices). 

1.6.1.1 Input Parameters 

The following are the device- or function-dependent arguments for 
IO$_CREATE: 

• PI—The address of the file information block (FIB) descriptor. 

• P2—The address of the file name string descriptor (optional). 

• P3—The address of the word that is to receive the length of the resultant 
file name string (optional). 

• P4—The address of a descriptor for a buffer that is to receive the resultant 
file name string (optional). 

• P5—The address of a list of attribute descriptors (optional). 

The following fields in the FIB are applicable to the IO$—CREATE operation: 


Field Field Values Meaning 

FIB$L_ACCTL Specifies field values that control 

access to the file. The following 
bits are applicable to the 
IO$_CREATE function: 

FIB$M_REWIND Set to rewind magnetic tape 

before creating the file. Any 
data currently on the tape is 
overwritten. 
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Field 

Field Values Meaning 

FIB$M_CURPOS Set to create magnetic tape file at 

the current tape position. (Note: 
a magnetic tape file is created 
at the end of the volume set 
if neither FIB$M_REWIND nor 
FIB$M_CURPOS is set.) If the 
tape is not positioned at the end 
of a file, FIB$M_CURPOS creates 
a file at the next file position. 

Any data currently on the tape 
past the current file position is 
overwritten. 

FIB$M_WRITETHRU Specifies that the file header is to 
be written back to the disk. If not 
specified and the file is opened, 
writing of the file header can be 
deferred to some later time. 

FIB$W_CNTRLFUNC 

Specifies the following value, 
which allows you to control 
actions subsequent to EOT 
detection on a magnetic tape file. 

FIB$C_USEREOT Set on a per file basis to specify 

user EOT mode. If this bit is set, 
the magnetic tape driver notifies 
the magnetic tape system if EOT 
has been detected (considered 
a 'serious exception') during the 
creation of a file. The magnetic 
tape system, in turn, returns 
the alternate success code 
SS$_ENDOFTAPE or SS$_ 
ENDOFVOLUME. All subsequent 
I/O requests are completed with 
a failure status return of SS$_ 
SERIOUSEXP. The driver does 
not execute any I/O functions 
until the serious exception has 
been explicitly cleared by issuing 
an IO$_ACPCONTROL function 
(see Section 1.6.7). If the file is 
deaccessed or closed, the user 
EOT mode is cleared after further 
processing of the magnetic tape. 

FIB$W_FID 

Contains the file ID of the file 
created or entered. 

FIB$W_DID 

Contains the file identifier of the 
directory file. 
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Field 

Field Values 

Meaning 

FIB$W_NMCTL 


Controls the processing of the 
file name in a directory operation. 
The following bits are applicable 
to the IO$_CREATE function: 


FIB$M_NEWVER 

Set to create file of same name 
with next higher version number. 
Only for disk devices. 


FIB$M_SUPERSEDE 

Set to supersede an existing file 
of the same name, type, and 
version. Only for disk devices. 


FIB$M_LOWVER 

Set on return if a lower numbered 
version of the file exists. Only for 
disk devices. 


FIB$M_HIGHVER 

Set on return if a higher numbered 
version of the file exists. Only for 
disk devices. 

FIB$W_VERLIMIT 


Specifies the version limit for the 
directory entry created. Used only 
for disk devices and only when 
the first version of a new file is 
created. If 0, the directory default 
is used. If a directory operation 
was performed, FIB$W_VERLIMIT 
always contains the actual version 
limit of the file. 

FIB$L_ACL_ 

STATUS 


Status of the requested ACL 
attribute operation, if any. The 
ACL attributes are included in 
Table 1-7. If no ACL attributes 
are given, SS$_NORMAL is 
returned here. 


1.6.1.2 Disk ACP Operation 

If the modifier IO$M_CREATE is specified, a file is created. The file ID of 
the file created is returned in FIB$W_FID. If the modifier IO$M—DELETE is 
specified, the file is marked for deletion. 

If a nonzero directory ID is specified in FIB$W_DID, a directory entry is 
created. The file name specified by parameter P2 is entered in the directory, 
together with the file ID in FIB$W— FID. (Section 1.3.1.1 describes the format 
for the file name string.) Wildcards are not permitted. Negative version 
numbers are treated as equivalent to a 0 version number. If a result string 
buffer and length are specified by P3 and P4, the actual file name entered, 
and its length, are returned. 

The version number of the file receives the following treatment: 

• If the version number in the specified file name is 0 or negative, the 

directory entry created gets a version number one greater than the highest 
previously existing version of that file (or version 1 if the file did not 
previously exist). 
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• If the version number in the specified file name is a nonzero number and 
FIB$M_NEWVER is set, the directory entry created gets a version number 
one greater than the highest previously existing version of that file, or the 
specified version number, whichever is greater. 

• If the version number in the specified file name is a nonzero number and 
the directory already contains a file of the same name, type, and version, 
the previously existing file is set aside for deletion if FIB$M—SUPERSEDE 
is specified. If FIB$M_SUPERSEDE is not specified, the create operation 
fails with an SS$—DUPFILNAM status. 

• If, after creating the new directory entry, the number of versions of the 
file exceeds the version limit, the lowest numbered version is set aside for 
deletion. 

• If the file did not previously exist, the new directory entry is given a 
version limit as follows: the version limit is taken from FIB$W—VERLIMIT 
if it is a nonzero number; if it is 0, the version limit is taken from the 
default version limit of the directory file; if the default version limit of the 
directory file is 0, the version limit is set to 32,767 (the highest possible 
number). 

The file name string entered in the directory is returned using the P3 and P4 
result string parameters, if present. The file name string is also written into 
the header. If no directory operation was requested (FIB$W_DID is 0), the file 
name string specified by P2, if any, is written into the file header. 

If an attribute list is specified by P5, a write attributes subfunction is 
performed (see Section 1.3.5). 

If the modifier IO$M —ACCESS is specified, the file is opened (see 
Section 1.3.2). 

If the extend enable bit FIB$M—EXTEND is specified in the FIB, an extend 
subfunction is performed (see Section 1.3.3). 

Finally, if a file was set aside for deletion (IO$M—DELETE is specified), that 
file is deleted. If the file is deleted because the FIB$M—SUPERSEDE bit was 
set, the alternate success status SS$—SUPERSEDE is returned in the I/O 
status block. If the file is deleted because the version limit was exceeded, the 
alternate success status SS$_FILEPURGED is returned. 

If an error occurs in the operation of an IO$_CREATE function, all actions 
performed to that point are reversed (the file is neither created nor changed), 
and the error status is returned to the user in the I/O status block. 


1.6.1.3 Directory Entry Creation 

Creating a new version of a file eliminates default access to the previously 
highest version of the file. For example, creating RESUME.TXT;4 masks 
RESUME.TXT;3 so that the DCL command TYPE RESUME.TXT yields the 
contents of version 4, not version 3. To protect the contents of the earlier 
version of a file, the creator of a file must have write access to the previous 
version of a file of the same name. 


1.6.1.4 Magnetic Tape ACP Operation 

No operation is performed unless the IO$M—CREATE modifier is specified. 
The magnetic tape is positioned as specified by FIB$M_REWIND and 
FIB$M_CURPOS, and the file is created. The name specified by the P2 
parameter is written into the file header label. 
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1.6.2 


If P5 specifies an attribute list, a write attributes subfunction is performed (see 
Section 1.3.5). 

If the modifier IO$M_ACCESS is specified, the file is opened (see 
Section 1.3.2). 


Access File 

This virtual I/O function searches a directory on a disk device or a magnetic 
tape for a specified file and accesses that file if found. 

The following is the function code: 

• IO$_ACCESS 

The following are the function modifiers: 

• IO$M_CREATE—Creates a file. 

• IO$M_ACCESS—Opens the file on your channel. 

1.6.2.1 Input Parameters 

The following are the device- or function-dependent arguments for 
IO$_ACCESS: 

• PI—The address of the file information block (FIB) descriptor. 

• P2—The address of the file name string descriptor (optional). 

• P3—The address of the word that is to receive the length of the resultant 
file name string (optional). 

• P4—The address of a descriptor for a buffer that is to receive the resultant 
file name string (optional). 

• P5—The address of a list of attribute descriptors (optional). 
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The following FIB fields are applicable to the IO$_ACCESS operation: 


Field 

Field Values Meaning 

FIB$W_CNTRLFUNC 

Specifies the value that allows the 
user to control actions subsequent 
to EOT detection on a magnetic 
tape file. 

FIB$C_USEREOT Set on a per file basis to specify 

user EOT mode. If this bit is 
set, the magnetic tape driver 
notifies the magnetic tape system 
when EOT has been detected 
(considered a 'serious exception') 
when a file is accessed. The 
magnetic tape system, in turn, 
returns the alternate success 
code SS$_ENDOFTAPE or SS$_ 
ENDOFVOLUME. All subsequent 
I/O requests are completed with 
a failure status return of SS$_ 
SERIOUSEXP. The driver does 
not execute any I/O functions 
until the serious exception has 
been explicitly cleared by issuing 
an IO$_ACPCONTROL function 
(see Section 1.6.7). If the file is 
deaccessed or closed, the user 
EOT mode is cleared after further 
processing of the magnetic tape. 

FIB$W_VERLIMIT 

Receives the version limit for the 
file. Applicable only if FIB$W_DID 
is a nonzero number (if a directory 
lookup is done). Used only for 
disk devices. 

FIB$L_ACL_ 

STATUS 

Status of the requested ACL 
attribute operation, if any. The 
ACL attributes are included in 
Table 1-7. If no ACL attributes 
are given, SS$_NORMAL is 
returned here. 

FIB$I_ST ATUS 

Alternate access status. The 
following bits are supported: 

FIB$V_ALT_REQ Set to indicate whether the 

alternate access bit is required 


for the current operation. If not 
set, the alternate access bit is 
optional. 
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Field 

Field Values 

Meaning 


FIB$V_ALT_ 

GRANTED 

If FIB$V_ALT_REQ = 0 and the 
alternate access check succeeded, 
the FIB bit returned from the file 
system is set. 

FIB$I_ALT- 

ACCESS 


A 32-bit mask that represents an 
access mask to check against file 
protection; for example, to open a 
file for read and to check whether 
it can be deleted. The mask has 
the same configuration as the 
standard protection mask. 


1.6.2.2 Operation 

If a nonzero directory file ID is specified in FIB$W_DID, a lookup subfunction 
is performed (see Section 1.3.1.) The version limit of the file found is returned 
in FIB$W_VERLIMIT. 

If the directory search fails with a 'file not found' condition and the 
IO$M_CREATE function modifier is specified, the function is reexecuted as a 
CREATE. In that case, the argument interpretations for IO$_CREATE, rather 
than those for IO$_ACCESS, apply. 

If IO$M_ACCESS is specified, an access subfunction is performed to open 
the file (see Section 1.3.2). 

If P5 specifies an attribute list, a read attributes subfunction is performed (see 
Section 1.3.5). 


1.6.3 Deaccess File 

Deaccess file is a virtual I/O function that deaccesses a file and, if specified, 
writes final attributes in the file header. 

The following is the function code: 

• IO$_DEACCESS 

IO$_DEACCESS takes no function modifiers. 

1.6.3.1 Input Parameters 

The following are the device- or function-dependent arguments for 
IO$_DEACCESS: 

• pi—The address of the file information block (FIB) descriptor. 

• ps—The address of a list of attribute descriptors (optional). 
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The following FIB field is applicable to a IO$_DEACCESS function: 


Field 

Field Values 

Meaning 

FIB$W_FID 


File identification of the file being 
deaccessed. This field can contain 
a value of 0. If it does not, it 
must match the file identifier of the 
accessed file. 

FIB$L_ACL_ 

STATUS 


Status of the requested ACL 
attribute operation, if any. The 

ACL attributes are included in 

Table 1-7. If no ACL attributes are 
given, SS$_NORMAL is returned 
here. 


1.6.3.2 Operation 

For disk files, if P5 specifies an attribute control list and the file was accessed 
for a write operation, a write attributes subfunction is performed (see 
Section 1.3.5). If the file was opened for write, no attributes were specified, 
and FIB$M_DLOCK was set when the file was accessed, the deaccess lock bit 
is set in the file header, inhibiting further access to that file. 

For disk files, if the truncate enable bit FIB$M_TRUNCATE is specified in the 
FIB, a truncate subfunction is performed (see Section 1.3.4). 

Finally, the file is closed. Trailer labels are written for a magnetic tape file 
that was opened for write. 


Modify File 

Modify file is a virtual I/O function that modifies the file attributes or 
allocation of a disk file. The IO$_MODIFY function is not applicable to 
magnetic tape. 

The following is the function code: 

• IO$_MODIFY 

IO$_MODIFY takes no function modifiers. 


1.6.4.1 Input Parameters 

The following are the device- or function-dependent arguments for 

IO$_MODIFY: 

• PI—The address of the file information block (FIB) descriptor. 

• P2—The address of the file name string descriptor (optional). If specified, 
the directory is searched for the name. 

• P3—The address of the word that is to receive the length of the resultant 
file name string (optional). 

• P4—The address of a descriptor for a buffer that is to receive the resultant 
file name string (optional). 

• P5—The address of a list of attribute descriptors (optional). 
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The following FIB fields are applicable to the IO$_MODIFY function: 


Field 

Field Values 

Meaning 

FIB$L_ACCTL 


Specifies field values that control 
access to the file. The following 
bits are applicable to the 
IO$_MODIFY function: 


FIB$M_ 

WRITETHRU 

Specifies that the file header is to 
be written back to the disk. If not 
specified and the file is currently 
open, writing of the file header can 
be deferred to some later time. 

FIB$W_VERLIMIT 


If a nonzero number, specifies the 
version limit for the file. 

FIB$L_ACL_ 

STATUS 


Status of the requested ACL 
attribute operation, if any. The 

ACL attributes are included in 

Table 1-7. If no ACL attributes are 
given, SS$_NORMAL is returned 
here. 


1.6.4.2 Operation 

If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction is 
executed (see Section 1.3.1). If a nonzero version limit is specified in 
FIB$W_VERLIMIT and the directory entry found is the latest version of that 
file, the version limit is set to the value specified. 

If P5 specifies an attribute list, a write attributes subfunction is performed (see 
Section 1.3.5). 

The file can be either extended or truncated. If FIB$M_EXTEND is specified 
in the FIB, an extend subfunction is performed (see Section 1.3.3). If 
FIB$M_TRUNCATE is specified in the FIB, a truncate subfunction is 
performed (see Section 1.3.4). Extend and truncate operations cannot be 
performed at the same time. 


1.6.5 Delete File 

Delete file is a virtual I/O function that removes a directory entry or file 
header from a disk volume. 

The following is the function code: 

• IO$_DELETE 

The following is the function modifier: 

• IO$M_DELETE—Deletes the file (or marks it for deletion). 

The following are the device- or function-dependent arguments for 
IO$_DELETE: 

• PI—The address of the file information block (FIB) descriptor. 

• P2—The address of the file name string descriptor (optional). 
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1.6.5.1 


• P3—The address of the word that is to receive the length of the resultant 
file name string (optional). 

• P4—The address of a descriptor for a buffer that is to receive the resultant 
file name string (optional). 

The following FIB fields are applicable to the IO$_DELETE function: 


Field 

Field Values 

Meaning 


FIB$I_ACCTL 


Specifies field values that control 
access to the file. The following 
bit is applicable to the IO$_DELETE 
function: 



FIB$M_ 

WRITETHRU 

Specifies that the file header is to 
be written back to the disk. If not 
specified and the file is currently 
open, writing of the file header can 
be deferred to some later time. 

• 

FIB$W_FID 


Specifies the file identification to be 
deleted. 



Operation 


If a nonzero directory ID is specified in FIB$W_DID, a lookup subfunction 
is performed (see Section 1.3.1). The file name located is removed from the 
directory. 


If the function modifier IO$M—DELETE is specified, the file is marked for 
deletion. If the file is not currently open, it is deleted immediately. If the file 
is open, it is deleted when the last accessor closes it. 


Mount 


ACP Control 


Mount is a virtual I/O function that informs the ACP when a disk or magnetic 
tape volume is mounted. MOUNT privilege is required. IO$_MOUNT takes 
no arguments or function modifiers. This function is a part of the volume 
mounting operation only, and it is not meant for general use. Most of the 
actual processing is performed by the MOUNT command or the Mount 
Volume ($MOUNT) system service. 


ACP Control is a virtual I/O function that performs miscellaneous control 
functions, depending on the arguments specified. 

The following is the function code: 

• IO$_ACPCONTROL 


The following is the function modifier: 

• IO$M_DMOUNT—Dismounts a volume. 
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1.6.7.1 Input Parameters 

The following are the device- or function-dependent arguments for 
IO$_ACPCONTROL: 

• PI—The address of the file information block (FIB) descriptor. 

• P2—The address of the file name string descriptor (optional). 

• P3—The address of the word that is to receive the length of the resultant 
file name string (optional). 

• P4—The address of a descriptor for a buffer that is to receive the resultant 
file name string (optional). 

The following FIB fields control the processing of the IO$_ACPCONTROL 
function: 


Field 

Field Values 

Meaning 

FIB$W_CNTRLFUNC 


Specifies the control function 
to be performed. This field 
overlays FIB$W_EXCTL. 

FIB$I_CNTRLVAL 


Specifies additional function- 
dependent data. This field 
overlays FIB$L_EXSZ. 

FIB$L _ACL _STATUS 


Status of the requested 

ACL attribute operation, if 
any. The ACL attributes are 
included in Table 1-7. If 
no ACL attributes are given, 
SS$_NORMAL is returned 
here. 

FIB$L-STATUS 


Alternate access status. The 
following bits are supported: 


FIB$V_ALT—REQ 

Set to indicate whether 
the alternate access bit 
is required for the current 
operation. If not set, the 
alternate access bit is 
optional. 


FIB$V_ALT_GRANTED 

If FIB$V_ALT_REQ = 0 
and the alternate access 
check succeeded, the FIB bit 
returned from the file system 
is set. 

FIBSL _ALT_ACCESS 


A 32-bit mask that represents 
an access mask to check 
against file protection; for 
example, to open a file for 
read and to check whether 
it can be deleted or not. 

The mask has the same 
configuration as the standard 
protection mask. 
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1.6.7.2 Magnetic Tape Control Functions 

The following FIB field is applicable to magnetic tape operations: 


Field 

Field Values 

Meaning 

FIB$W_CNTRLFUNC 


Several ACP control functions 
are used for magnetic tape 
positioning. These functions 
are specified by supplying a 

FIB with PI containing the FIB 
descriptor address. Modifiers 
and parameters P2, P3, and 

P4 are not allowed. These 
functions clear serious exceptions 
in magnetic tape drivers. The 
following control functions can be 
specified to control magnetic tape 
positioning: 


FIB$C_REWINDFIL 

Rewind to beginning-of-file. 


FIB$C_REWINDVOL 

Rewind to beginning-of-volume 
set. 


FIB$C_POSEND 

Position to end-of-volume set. 


FIB$C_NEXTVOL 

Force next volume. 


FIB$C_SPACE 

Space n blocks forward 

or backward. The FIB$I_ 

CNTRLVAL field specifies the 
number of magnetic tape blocks 
to space forward if positive or to 
space backward if negative. 


FIB$C_CLSEREXCP 

If set, clears the serious exception 
in the magnetic tape driver (see 
FIB$C_USEREOT in Sections 

1.6.1 and 1.6.2). This allows 
the user to write data blocks 
beyond the EOT marker, which 
can result in the magnetic tape 
not conforming to the ANSI 
standard for magnetic tapes (see 
ANSI Standard X3.27 - 1978). 


1.6.7.3 Miscellaneous Disk Control Functions 

Several ACP control functions are available for disk volume control. The 
following function does not use parameters P2, P3, and P4: 

IO$M_DMOUNT Specifying the dismount modifier on the IO$_ACPCNTRL 

function executes a dismount QIO. No parameters in 
the FIB are used; the FIB can be omitted. This function 
does not perform a dismount by itself, but is used to 
synchronize the ACP with the DISMOUNT command and 
the Dismount Volume ($DISMOUNT) system service. 
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1.6.7.4 


The FIB$W_CNTRLFUNC field of the FIB specifies the following 
miscellaneous control functions (with no modifier on the IO$_ACPCONTROL 
function code). These functions use no other parameters. 

FIB$C_REMAP Remap a file. The file window for the file open on the 

user's channel is remapped so that it maps the entire file. 

FIB$C_LOCK_VOL Allocation lock the volume. Operations that change the 
file structure, such as file creation, deletion, extension, 
and deaccess, are not permitted. If such requests are 
queued to the file system for an allocation-locked volume, 
they are not processed until the FIB$C_UNLK_VOL 
function is issued to unlock the volume. 


To issue the FIB$C_LOCK_VOL function, you must have 
either a system UIC or SYSPRV privilege, or be the owner 
of the volume. 

FIB$C_UNLK_VOL Unlock the volume. Cancels FIB$C_LOCK_VOL. To issue 
this function, you must have either a system UIC or 
SYSPRV privilege, or be the owner of the volume. 


Disk Quotas 

Disk quota enforcement is enabled by a quota file on the volume, or relative 
volume 1 if the file is on a volume set. The quota file appears in the volume's 
master file directory (MFD) under the name QUOTA.SYS;l. This section 
describes the control functions that operate on the quota file. 

Table 1-11 lists the enable and disable quota control functions. 


Table 1-11 Disk Quota Functions (Enable/Disable) 


Value 

Meaning 

FIB$C_EN A _QUOT A 

Enable the disk quota file. If a nonzero directory file 

ID is specified in FIB$W_DID, a lookup subfunction is 
performed to locate the quota file (see Section 1.3.1). 
To issue this function, you must have either a system 
UIC or SYSPRV privilege, or be the owner of the 
volume. 


The quota file specified by FIB$W_FID, if present, 
is accessed by the ACP, and quota enforcement is 
turned on. By convention, the quota file is named 
[0,0]QUOTA.SYS; 1. Therefore, FIB$W_DID should 
contain the value 4,4,0 and the name string specified 
with P2 should be “QUOTA.SYS,r. 

FIB$C_DS A —QUOT A 

Disable the disk quota file. The quota file is 
deaccessed and quota enforcement is turned off. 

To issue this function, you must have either a system 
UIC or SYSPRV privilege, or be the owner of the 
volume. 


Table 1-12 lists the quota control functions that operate on individual entries 
in the quota file. Each operation transfers quota file data to and from the ACP 
using a quota data block. This block has the same format as a record in the 
quota file. Figure 1-9 shows the format of this block. 
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IO$_ACPCONTROL functions that transfer quota file data between the caller 
and the ACP use the following device- or function-dependent arguments: 

• P2—The address of a descriptor for the quota data block being sent to the 
ACP. 

• P3—The address of a word that returns the data length. 

• P4—The address of a descriptor for a buffer to receive the quota data 
block returned from the ACP. 

Table 1-12 Disk Quota Functions (Individual Entries) 

Value Meaning 

FIB$C_ADD_QUOTA Add an entry to the disk quota file, using the UIC and 

quota specified in the P2 argument block. FIB$C_ 
ADD_QUOTA requires write access to the quota file. 

FIB$C_EXA_QUOTA Examine a disk quota file entry. The entry whose UIC 

is specified in the P2 argument block is returned in 
the P4 argument block, and its length is returned in 
the P3 argument word. Using two flags in 
FIB$L_CNTRLVAL, it is possible to search through 
the quota file using wildcards. The two flags are: 

FIB$M_ALL_MEM Match all UIC members 

FIB$M_ALL_GRP Match all UIC groups 

The ACP maintains position context in FIB$I_WCC. 

On the first examine call, you specify 0 in 
FIB$L_WCC; the ACP returns a nonzero value so 
that each succeeding examine call returns the next 
matching entry. 

Read access to the quota file is required to examine 
all non-user entries. 

FIB$C_MOD_QUOTA Modify a disk quota file entry. The quota file entry 

specified by the UIC in the P2 argument block is 
modified according to the values in the block, as 
controlled by three flags in FIB$L_CNTRLVAL: 

FIB$M_MOD_ Change the permanent quota 

PERM 

FIB$M_MOD_ Change the overdraft quota 

OVER 

FIB$M_MOD_USE Change the usage data 

The usage data can be changed only if the volume is 
locked by FIB$C_LOCK_VOL (see Section 1.6.7.3). 
FIB$C_MOD_QUOTA requires write access to the 
quota file. 

The P3 and P4 arguments return the modified quota 
entry to you. 

By using the flags FIB$M_ALI_MEM and FIB$M_ 

ALI—GRP, you can search through the quota file 
using wildcards just as you would with the 
FIB$C_EXA_QUOTA function. 
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Table 1-12 (Cont.) Disk Quota Functions (Individual Entries) 

Value Meaning 

FIB$C_REM_QUOTA Remove a disk quota file entry whose UIC is specified 

in the P2 argument block. FIB$C_REM_QUOTA 
requires write access to the quota file. 

The P3 and P4 arguments return the removed quota 
file entry to you. 

By using the flags FIB$M_ALI—MEM and 

FIB$M_ALI_GRP, you can search through the quota 

file using wildcards just as you would with the 
FIB$C_EXAQUOTA function. 


Figure 1-9 Quota File Transfer Block 


31 0 


Flags Longword (DQF$L__FLAGS) 


User Identification Code (DQF$L_UIC) 


Current Usage (DQF$L_USAGE) 


Permanent Quota (DQF$L__PERMQUOTA) 


Overdraft Limit (DQF$L_OVERDRAFT) 


(reserved for future use) 


ZK-643-82 
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1.7 I/O Status Block 


Figure 1-10 shows the I/O status block (IOSB) for ACP-QIO functions. 
Appendix A lists the status returns for these functions. (The VMS System 
Messages and Recovery Procedures Reference Volume provides explanations and 
suggested user actions for these returns.) 

The file ACP returns a completion status in the first longword of the IOSB. 

In an extend operation, the second longword is used to return the number of 
blocks allocated to the file. If a contiguous extend operation 
(FIB$M_ALCON) fails, the second longword is used to return the size of the 
file after truncation. 

Values returned in the IOSB are most useful during operations in 
compatibility mode. When executing programs in the native mode, use 
the values returned in FIB locations. 

Figure 1-10 IOSB Contents - ACP—QIO Functions 


+2 IOSB 


not used 

status 



+4 

ZK-644-82 


If an extend operation (including CREATE) was performed, IOSB+4 contains 
the number of blocks allocated, or the largest available contiguous space if a 
contiguous extend operation failed. If a truncate operation was performed, 
IOSB+4 contains the number of blocks added to the file size to reach the next 
cluster boundary. 
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Card Reader Driver 


This chapter describes the use of the VMS card reader driver that supports 
the CR11 card reader. 


2.1 Supported Card Reader Device 

The CR11 card reader reads standard 80-column punched data cards. 


2.2 Driver Features 

The VMS card reader driver provides the following features: 

• Support for multiple controllers of the same type; for example, more than 
one CR11 can be used on the system 

• Binary, packed Hollerith, and translated 026 or 029 read modes 

• Unsolicited interrupt support for automatic card reader input spooling 

• Special card punch combinations to indicate an end-of-file condition and 
to set the translation mode 

• Error recovery 

The following sections describe the read modes, special card punch 
combinations, and error recovery in greater detail. 

The VMS operating system provides the following card reader device- or 
function-dependent modifier bits for read data operations: 

• IO$M_PACKED—Read packed Hollerith code 

• IO$M_BINARY—Read binary code 

If IO$M_PACKED is set, the data is packed and stored in sequential bytes 
of the input buffer. If IO$M_BINARY is set, the data is read and stored in 
sequential words of the input buffer. IO$M—BINARY takes precedence over 
IO$M_PACKED. 

The read mode can also be set by a special card punch combination that sets 
the translation mode (see Section 2.2.1.2), or by the set mode function (see 
Section 2.4.3). 


2.2.1 Special Card Punch Combinations 

The VMS card reader driver recognizes three special card punch combinations 
in column 1 of a card. One combination signals an end-of-file condition. The 
other two combinations set the current translation mode. 
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2.2.1.1 End-of-File Condition 

A card with the 12-11-0-1-6-7-8-9 holes punched in column 1 signals an 
end-of-file condition. If the read mode is binary, the first eight columns must 
contain that punch combination. 


2.2.1.2 Set Translation Mode 

If the read mode is nonbinary, nonpacked Hollerith (the IO$M_BINARY 
and IO$M_PACKED function modifiers are not set), the current translation 
mode can be set to the 026 or 029 punch code. (Table 2-5 lists the 026 
and 029 punch codes.) A card with the 12-2-4-8 holes punched in column 
1 sets the translation mode to the 026 code. A card with the 12-0-2-4-6-8 
holes punched in column 1 sets the translation mode to the 029 code. The 
translation mode can be changed as often as required. 

If a translation mode card contains punched information in columns 2 
through 80, it is ignored. 

The system can read cards that were punched on an 026 punch or an 029 
punch. By default, the translation mode is 029; that is, the system reads cards 
from an 029 punch. However, you can change the translation mode by using 
the following: 

• The SET CARD-READER command 

• Translation mode cards 

Use the SET CARD-READER command, with the /026 or /029 qualifier, to 
set the card reader to accept cards from either an 026 or an 029 card punch. 

Logical, virtual, and physical read functions result in only one card being 
read. If a translation mode card is read, the read function is not completed, 
and another card is read immediately. 


2.2.2 Submitting Batch Jobs Through the Card Reader 

When you submit a batch job through a system card reader, precede the 
card deck containing the command procedure with cards containing JOB and 
PASSWORD commands. These cards specify your user name and password 
and, when executed, effect a login for you. The last card in the deck must 
contain the EOJ (End of Job) command. The EOJ card is equivalent to logging 
out. You can also use an overpunch card instead of an EOJ card to signal the 
end of a job. To do this, use an EOF card (12-11-0-1-6-7-8-9) overpunch or 
use the EOJ command. Figure 2-1 illustrates a card reader batch job. 
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When the system reads a job from the card reader, it validates the user name 
and password specified on the JOB and PASSWORD cards. Then, it copies 
the entire card deck into a temporary disk file named INPBATCH.COM in 
your default disk and directory, and it queues the job for batch execution. 
Thereafter, processing is the same as for jobs submitted interactively with the 
SUBMIT command. When the batch job is completed, the operating system 
deletes the INPBATCH.COM file. 

You can prevent other users from seeing your password by suppressing 
printing when you keypunch the PASSWORD card. 


2.2.3 Passing Data to Commands and Images 

To pass data to commands and images in batch jobs that you submit through 
a card reader, you can do the following: 

• Include the data in the command procedure by placing the data on the 
lines after the command or image that uses the data. Use the DECK and 
EOD commands if the data lines begin with dollar signs. 

• Temporarily redefine SYS$INPUT as a file by using the 
DEFINE/USER-MODE command. 
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2.2.4 Error Recovery 

The VMS card reader driver performs the following error recovery operations: 

• If the card reader is offline for 30 seconds, a "device not ready" message 
is sent to the system operator. 

• If a recoverable card reader failure is detected, a "device not ready" 
message is sent every 30 seconds to the system operator. 

• The current operation is retried every two seconds to test for a changed 
situation, such as the removal of an error condition. 

• The current I/O operation can be canceled at the next timeout without 
the card reader being online. When the card reader comes online, device 
operation resumes automatically. 

When a recoverable card reader failure is detected and an error message is 
displayed on the system operator console, examine the card reader indicator 
lights to determine the reason for the failure. Any errors that occur must be 
fixed manually. The recovery is transparent to the user program issuing the 
I/O request. 

The four categories of card reader failures and their respective recovery 
procedures are as follows: 

• Pick check—The next card cannot be delivered from the input hopper 
to the read mechanism. To recover from this error, remove the next 
card to be read from the input hopper and smooth the leading edge 
(the edge that enters the read mechanism first). Replace the card in the 
input hopper and press the RESET button. The card reader operation 
resumes automatically. If a pick check error occurs again on the same 
card, remove the card from the input hopper and repunch it. Place the 
duplicate card in the input hopper and press the RESET button. If the 
problem persists, either an adjustment is required, or nonstandard cards 
are in the input hopper. 

• Stack check—The card just read did not stack properly in the output 
hopper. To recover from this error, remove the last card read from the 
output hopper and examine it. If it is excessively worn or mutilated, 
repunch it. Place either card in the read station of the input hopper 
and press the RESET button. The card reader operation resumes 
automatically. If the stack check error recurs immediately, an adjustment 
is required. 

• Hopper check—Either the input hopper is empty or the output hopper is 
full. To recover from this error, examine the input hopper and, if empty, 
either load the next deck of input cards or an end-of-file card. If the input 
hopper is not empty, remove the cards that have accumulated in the 
output hopper and press the RESET button. The card reader operation 
resumes automatically. 

• Read check—The last card was read incorrectly. To recover from this 
error, remove the last card from the output hopper and examine it. If it 
is excessively worn, mutilated, or contains punches before column 0 or 
after column 80, repunch the card. Place either card in the read station of 
the input hopper and press the RESET button. The card reader operation 
resumes automatically. If the read check error recurs immediately, an 
adjustment is necessary. 
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2.3 Device Information 

You can obtain information on card reader characteristics by using the Get 
Device/Volume Information ($GETDVI) system service. See the VMS System 
Services Reference Manual. 

$GETDVI returns card reader characteristics when you specify the item 
codes DVI$_DEVCHAR and DVI$_DEVDEPEND. Tables 2-1 and 
2-2 list these characteristics. The $DEVDEF macro defines the device¬ 
independent characteristics; the $CRDEF macro defines the device-dependent 
characteristics. 

DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and device 
class names, which are defined by the $DCDEF macro. The device class for 
card readers is DC$_CARD. The device type for the CR11 is DT$_CR11. 
DVI$_DEVBUFSIZ returns the buffer size. The default buffer size to be used 
for all card reader devices is 80 bytes. 


Table 2-1 Card Reader Device-Independent Characteristics 


Characteristic 1 

Meaning 

Dynamic Bit (Conditionally Set) 

DEV$M_AVL 

Device is online and available 

Static Bits (Always Set) 

DEV$M_IDV 

DEV$M_REC 

Device is capable of input 

Device is record-oriented 

1 Defined by the $DEVDEF macro. 

Table 2—2 Device-Dependent Characteristics for Card Readers 

Value 1 

Meaning 

CR$V_TMODE 

CR$S_TMODE 

Specifies the translation mode for nonbinary, nonpacked 
Hollerith data transfers. 2 Possible values are: 

CR$K_T026 Translate according to 026 punch code 
CR$K_T029 Translate according to 029 punch code 

defined by the $CRDEF macro. 

2 Section 2.2.1.2 describes the set translation mode punch code. 


2.4 Card Reader Function Codes 

The VMS card reader can perform logical, virtual, and physical I/O functions. 
Table 2-3 lists these functions and their function codes. These functions are 
described in more detail in the sections that follow. 
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Table 2—3 Card Reader I/O Functions 


Function Code and 
Arguments 

Type 1 

Function 

Modifiers 

Function 

IO$_READLBLK P1.P2 

L 

IO$M_BINARY 

IO$M_PACKED 

Read logical block. 

IO$_READVBLK P1,P2 

V 

IO$M_BINARY 

IO$M_PACKED 

Read virtual block. 

IO$_READPBLK P1,P2 

P 

IO$M_BINARY 

IO$M_PACKED 

Read physical block. 

IO$_SENSEMODE 

L 


Sense the card reader 
characteristics and 
return them in the I/O 
status block. 

IO$_SETMODE PI 

L 


Set card reader 
characteristics for 
subsequent operations. 

IO$_SETCHAR PI 

P 


Set card reader 
characteristics for 
subsequent operations. 

1 V = virtual; L = logical; P = 

physical 




Read 


Read is a function that reads data from the next card in the card reader input 
hopper into the designated memory buffer in the specified format. Only one 
card is read each time a read function is specified. 

The VMS operating system provides the following read function codes: 

• IO$_READVBLK—Read virtual block 

• IO$_READLBLK—Read logical block 

• IO$_READPBLK—Read physical block 

The following function-dependent arguments are used with these codes: 

• PI—The starting virtual address of the buffer that is to receive the data 

• P2—The number of bytes that are to be read in the specified format 

The read binary function modifier (IO$M_BINARY) and the read packed 
Hollerith function modifier (IO$M —PACKED) can be used with all read 
functions. If IO$M_BINARY is specified, successive columns of data are 
stored in sequential word locations of the input buffer. If IO$M_PACKED is 
specified, successive columns of data are packed and stored in sequential byte 
locations of the input buffer. If neither of these function modifiers is specified, 
successive columns of data are translated in the current mode (026 or 029) 
and are stored in sequential bytes of the input buffer. Figure 2-2 shows how 
data is stored by IO$M_BINARY and IO$M_PACKED. 
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Figure 2-2 Binary and Packed Column Storage 


Binary column (IO$M__BINARY): 

15 12 11 _0 

* 1211 0123456789 

*Bits 12 - 15 are 0 


Packed column (IO$M_PACKED): 
7 3 2 0 


12 11 0 9 8 


*n = 0 if no punches in rows 1 - 7 
= 1 if a punch in row 1 
= 2 if a punch in row 2 


= 7 if a punch in row 7 

ZK-646-82 


Regardless of the byte count specified by the P2 argument, a maximum 
of 160 bytes of data for binary read operations and 80 bytes of data for 
nonbinary read operations (IO$M—PACKED, or 026 or 029 modes) are 
transferred to the input buffer. If P2 specifies less than the maximum quantity 
for the respective mode, only the number of bytes specified are transferred; 
any remaining buffer locations are not filled with data. 


2.4.2 Sense Mode 

Sense mode is a function that senses the current device-dependent card 
reader characteristics and returns them in the second longword of the I/O 
status block (see Table 2-2). No device- or function-dependent arguments are 
used with IO$_SENSEMODE. 


2.4.3 Set Mode 

Set mode operations affect the operation and characteristics of the associated 
card reader device. The VMS operating system defines the following types of 
set mode functions: 

• Set mode 

• Set characteristic 
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2.4.3.1 Set Mode 

The set mode function affects the characteristics of the associated card reader. 
Set mode is a logical I/O function and requires the access privilege necessary 
to perform logical I/O. The following function code is provided. 

• IO$_SETMODE 

This function takes the following device- or function-dependent argument: 

• PI—The address of a characteristics buffer 

Figure 2-3 shows the quadword set mode characteristics buffer. 

Figure 2-3 Set Mode Characteristics Buffer 


31 


16 15 


buffer size 


not used 


card reader characteristics 


Table 2-4 lists the card reader characteristics and their meanings. The 
$CRDEF macro defines the characteristics values. Table 2-5 lists the 026 and 
029 card reader codes. 

Table 2-4 Set Mode and Set Characteristic Card Reader 
Characteristics 

Value 1 Meaning 


CR$V_TMODE Specifies the translation mode for nonbinary, nonpacked 
CR$S_TMODE Hollerith data transfers. Possible values are: 

CR$K_T026 Translate according to 026 punch code 
CR$K_T029 Translate according to 029 punch code 


1 1f neither the 026 nor 029 mode is specified, the default mode can be set by the 
SET CARD_READER command. 


Table 2-5 Card Reader Codes 


Character 

ASCIIs 

DEC029 

DEC026 

i 

173 

12 0 

12 0 

i 

175 

11 0 

11 0 

SPACE 

40 

NONE 

NONE 

! 

41 

118 2 

12 8 7 

II 

42 

8 7 

0 8 5 
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Table 2-5 (Cont.) Card Reader Codes 


Character 

ASCIIg 

DEC029 

DEC026 


43 

8 3 

0 8 6 

$ 

44 

118 3 

118 3 

% 

45 

0 8 4 

0 8 7 

& 

46 

12 

118 7 

/ 

47 

8 5 

8 6 

< 

50 

12 8 5 

0 8 4 

> 

51 

118 5 

12 8 4 

* 

52 

118 4 

118 4 

+ 

53 

12 8 6 

12 

, 

54 

0 8 3 

0 8 3 

- 

55 

11 

11 


56 

12 8 3 

12 8 3 

/ 

57 

0 1 

0 1 

0 

60 

0 

0 

1 

61 

1 

1 

2 

62 

2 

2 

3 

63 

3 

3 

4 

64 

4 

4 

5 

65 

5 

5 

6 

66 

6 

6 

7 

67 

7 

7 

8 

70 

8 

8 

9 

71 

9 

9 


72 

8 2 

118 2 

/ 

73 

118 6 

0 8 2 

< 

74 

12 8 4 

12 8 6 

= 

75 

8 6 

8 3 

> 

76 

0 8 6 

118 6 

? 

77 

0 8 7 

12 8 2 

@ 

100 

8 4 

8 4 

A 

101 

12 1 

12 1 

B 

102 

12 2 

12 2 

C 

103 

12 3 

12 3 

D 

104 

12 4 

12 4 

E 

105 

12 5 

12 5 

F 

106 

12 6 

12 6 

G 

107 

12 7 

12 7 

H 

110 

12 8 

12 8 
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Table 2-5 (Cont.) Card Reader Codes 


Character 

ASCIIg 

DEC029 

DEC026 

1 

111 

12 9 

12 9 

J 

112 

11 1 

11 1 

K 

113 

11 2 

11 2 

L 

114 

11 3 

11 3 

M 

115 

11 4 

11 4 

N 

116 

11 5 

11 5 

0 

117 

11 6 

11 6 

p 

120 

11 7 

11 7 

Q 

121 

11 8 

11 8 

R 

122 

11 9 

11 9 

S 

123 

0 2 

0 2 

T 

124 

0 3 

0 3 

U 

125 

0 4 

0 4 

V 

126 

0 5 

0 5 

w 

127 

0 6 

0 6 

X 

130 

0 7 

0 7 

Y 

131 

0 8 

0 8 

z 

132 

0 9 

0 9 

[ 

133 

12 8 2 

118 5 

\ 

134 

118 7 

8 7 

] 

135 

0 8 2 

12 8 5 

T or A 

136 

12 8 7 

8 5 

<— or _ 

137 

0 8 5 

8 2 


Application programs that change specific card reader characteristics should 
first use the IO$_SENSEMODE function to read the current characteristics, 
modify them, and then use the set mode function to write back the 
results. Failure to follow this sequence results in clearing any previously 
set characteristic. 


2.4.3.2 Set Characteristic 

The set characteristic function also affects the characteristics of the associated 
card reader device. Set characteristic is a physical I/O function, and requires 
the access privilege necessary to perform physical I/O functions. The 
following function code is provided: 

• IO$_SETCHAR 

This function takes the following device- or function-dependent argument: 

• PI—The address of a characteristics buffer 
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2.5 


Figure 2-4 shows the set characteristic characteristics buffer. 

Figure 2-4 Set Characteristic Buffer 


31 _ 16 15 _87_0 


buffer size 

type 

class 

card reader characteristics 
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The device type value is DT$_CR11. The device class value is DC$_CARD. 
Table 2-4 lists the card reader characteristics for the Set Characteristic 
function. 


I/O Status Block 

The I/O status block (IOSB) format for QIO functions on the card reader is 
shown in Figure 2-5. Appendix A lists the status returns for these functions. 
(The VMS System Messsages and Recovery Procedures Reference volume provides 
explanations and suggested user actions for these returns.) Table 2-2 lists the 
device-dependent data returned in the second longword. The 
IO$_SENSEMODE function can be used to obtain this data. 

Figure 2—5 IOSB Contents 


31 


16 15 


byte count 


status 


device-dependent data 
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Disk Drivers 


This chapter describes the use of VMS disk drivers. These drivers support the 
devices listed in Table 3-1. 

All disk drivers support Files-11 On-Disk Structure Level 1 and Level 2 file 
structures. Access to these file structures is through the DCL commands 
INITIALIZE and MOUNT, followed by the VMS RMS calls described in the 
VMS Record Management Services Manual Files in RT-11 format can be read 
or written with the file exchange facility EXCHANGE. 


Supported Disk Devices and Controllers 

The following sections provide greater detail about the disk devices listed 
in Table 3-1. To obtain additional information about a device, use the DCL 
command SHOW DEVICE with the /FULL qualifier, the Get Device/Volume 
Information ($GETDVI) system service (from a program), or the F$GETDVI 
lexical function (in a command line or command procedure). Section 3.3 lists 
the information on disk devices returned by $GETDVI. 


Table 3—1 Supported Disk Devices 


Disk 

Device 

Code 

Type 

DSA 

Logical Blocks/Drive 

RA60 

DJ 

Packed 

Yes 

400,176 

RA70 

DU 

Fixed 

Yes 

547,041 

RA80 

DU 

Fixed 

Yes 

236,964 

RA81 

DU 

Fixed 

Yes 

891,072 

RA82 

DU 

Fixed 

Yes 

1,216,665 

RB02 

DQ 

Cartridge 

No 

20,480 

RB80 

DQ 

Fixed 

No 

242,606 

RC25 

DA 

Fixed, 

Cartridge 

Yes 1 

102,400 2 

RRD50 

DU 

Optical 

Yes 1 

1,669,400 

RD32 

DU 

Fixed 

Yes 1 

83,204 

RD51 

DU 

Fixed 

Yes 1 

21,600 

RD52 

DU 

Fixed 

Yes 1 

60,480 

RD53 

DU 

Fixed 

Yes 1 

138,672 

RD54 

DU 

Fixed 

Yes 1 

311,200 

RL02 

DL 

Cartridge 

No 

20,480 

RM03 

DR 

Packed 

No 

131,680 


'Incompatible with the UDA50, KDA50 and KDB50 disk devices. 
2 51,200 fixed; 51,200 cartridge. 
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Table 3-1 (Cont.) Supported Disk Devices 
Disk 


Device 

Code 

Type 

DSA 

Logical Blocks/Drive 

RM05 

DR 

Packed 

No 

500,384 

RM80 

DR 

Fixed 

No 

242,606 

RP05 

DB 

Packed 

No 

171,798 

RP06 

DB 

Packed 

No 

340,670 

RP07 

DR 

Fixed 

No 

1,008,000 

RK06 

DM 

Cartridge 

No 

27,126 

RK07 

DM 

Cartridge 

No 

53,790 

RX01 

DX 

Flexible 

No 

494 

RX02 

DY 

Flexible 

No 

494 3 

988 4 

RX33 

DU 

Flexible 

Yes 1 

2,400 

RX50 

DU 

Flexible 

Yes 1 

800 

TU58 5 

DD 

Cartridge 

No 

512 


incompatible with the UDA50, KDA50 and KDB50 disk devices. 

3 Single density (See Section 3.3). 

4 Double density (See Section 3.3). 

5 A magnetic tape device, the TU58 operationally resembles a disk device. See 
Section 3.1.16 for a description of the TU58 in disk terms. 


3.1.1 UDA50 UNIBUS Disk Adapter 

The UDA50 UNIBUS Disk Adapter (UDA50) is a microprocessor-based disk 
controller for mass storage devices that implement the DIGITAL Storage 
Architecture (DSA); for more information on the DSA, see Section 3.2.1.3. 

The UDA50 is used to connect any combination of four RA60, RA80, and 
RA81 disk drives to the UNIBUS. Two UDA50 controllers can be attached 
to a single UNIBUS for a maximum of eight disk drives per UNIBUS. On 
the VAX-11/780 processor, the VMS operating system supports one UDA50 
on the first UNIBUS, which can accomodate certain other options. Adding 
a second UDA50 requires a second UNIBUS. With the exception of the first 
UNIBUS, a maximum of two UDA50s per UNIBUS are supported. If two 
UDA50s are on a UNIBUS, no other options can be placed on that UNIBUS. 
The VAX-11/730 processor supports only one UDA50 per UNIBUS. 

The UDA50, in implementing DSA, takes over the control of the physical 
disk unit. The VMS operating system processes request virtual or logical I/O 
on disks controlled by the UDA50. The VMS operating system maps virtual 
block addresses into logical block addresses. The UDA50 then resolves logical 
block addresses into physical block addresses on N the disk. 

The UDA50 corrects bad blocks on the disk by requesting that the disk class 
driver revector a failing physical block to another, error-free physical block on 
the disk; the logical block number is not changed (see Section 3.2.6.1). Any 
bad blocks might exist on a disk attached to a UDA50 are transparent to the 
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VMS operating system, which does logical or virtual I/O to such a disk. The 
UDA50 also corrects most data errors. 


3.1.2 KDA50 Disk Controller 

The KDA50 disk controller is a two-module disk controller that allows the 
RA series DSA disk drives to be attached to Q-BUS systems. The KDA50 
performs the same functions as the UDA50 (see Section 3.1.1). 


3.1.3 KDB50 Disk Controller 

The KDB50 disk controller is a two-module disk controller that allows the RA 
series DSA disk drives to be attached to BI bus systems, such as the 
VAX 8200 processor. The KDB50 performs the same functions as the UDA50 
(see Section 3.1.1). 


3.1.4 HSC50 Controller 

The HSC50 is a high-speed, high-availability controller for mass storage 
devices that implement the DIGITAL Storage Architecture (DSA); for more 
information about the DSA, see Section 3.2.1.3. The HSC50 is connected 
to a processor by a Computer Interconnect (Cl). The VMS operating system 
supports the use of the HSC50 in controlling the RA60, RA80, and RA81 
disks. 

The HSC50, in implementing DSA, takes over the control of the physical disk 
unit. VMS operating system processes request virtual or logical I/O on disks 
controlled by the HSC50. The VMS operating system maps virtual block 
addresses into logical block addresses. The HSC50 then resolves logical block 
addresses into physical block addresses on the disk. 

The HSC50 corrects bad blocks on the disk by revectoring a failing physical 
block to another, error-free physical block on the disk; the logical block 
number is not changed. The VMS operating system, which does logical or 
virtual I/O to such a disk, does not recognize that any bad blocks might exist 
on a disk attached to an HSC50. The HSC50 also corrects most data errors. 

The HSC50 provides access to disks despite most hardware failures, and it 
enables two or more processors to access files on the same disk. 

Note: Only one system should have write access to a Files-11 On-Disk Structure 
Level 1 disk or to a foreign-mounted disk; all other systems should only 
have read access to the disk. For Files-11 On-Disk Structure Level 2 
volumes, the VMS operating system enables read/write access to all 
nodes that are members of the same VAXcluster. 

The HSC50 enables you to add or subtract disks from the device configuration 
without rebooting the system. 
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3.1.5 RA60 Pack Disk 

The RA60 is a large-capacity, removable disk that provides 205 MB of usable 
storage (7.5 million bits of data per square inch) with transfer rates 
of 1.9 MB/second (burst) and 950 KB/second (sustained). The RA60 belongs 
to the DIGITAL Storage Architecture (DSA) family of disk devices (see 
Section 3.2.1.3). It is connected to either a UNIBUS Disk Adapter (UDA50) or 
an HSC50 controller. Up to 4 disk drives can be connected to each UDA50. 
Up to 24 disk drives can be connected to each HSC50. 


3.1.6 RB02 and RL02 Cartridge Disks 

The RL02 cartridge disk is a removable, random-access mass storage device 
with two data surfaces. The RL02 is connected to the system by an RL11 
controller that interfaces with the UNIBUS adapter. Up to four RL02 disk 
drives can be connected to each RL11 controller. For physical I/O transfers, 
the track, sector, and cylinder parameters describe a physical 256-byte RL02 
sector (see Section 3.4). 

When the RL02 is connected to an RB730 controller on a VAX-11/730 
processor, it is identified internally as an RB02 disk drive. Disk geometry 
is unchanged and RL02 disk packs can be exchanged between drives on 
different controllers. Up to four drives can be connected to the RB730 
controller. 


3.1.7 RM03 and RM05 Pack Disks 

The RM03 and RM05 pack disks are removable, moving-head disks that 
consist of five data surfaces for the RM03 and 19 data surfaces for the RM05. 
These disks are connected to the system by a MASSBUS adapter (MBA). Up 
to eight disk drives can be, connected to each MBA. 


3.1.8 RA80/R80/RM80 and RA81 Fixed Media Disks 

The R80 is a nonremovable, large capacity, moving-head disk that consists of 
14 data surfaces. Depending on how it is connected to the system, the R80 is 
identified internally as an RA80, RB80, or RM80, as follows: 

• RA80—An R80 connected to the system through a UNIBUS disk adapter 
(UDA50) or an HSC50 controller. Up to four disk drives can be connected 
to each UDA50. Up to 24 disk drives can be connected to each HSC50. 

• RB80—An R80 connected to the system through an RB730 controller on 
a VAX 11/730 processor. Of the maximum of four drives that can be 
connected to an RB730 controller, only one can be an RB80. 

• RM80—An R80 connected to the system through a MASSBUS adapter 
(MBA). Up to eight disk drives can be connected to each MBA. 

The RA81 is a large-capacity, nonremovable disk that can hold more than 
890,000 blocks of data. This translates into more than 455 MB per spindle. 
The RA81 is connected to a UDA50 or an HSC50 controller. Up to four disk 
drives can be connected to each UDA50. Up to 24 drives can be connected to 
each HSC50. 
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3.1 Supported Disk Devices and Controllers 


The RA80 and RA81 belong to the DIGITAL Storage Architecture (DSA) 
family of disk devices (see Section 3.2.1.3). 


3.1.9 RP05 and RP06 Pack Disks 

The RP05 and RP06 pack disks consist of 19 data surfaces and a moving 
read/write head. The RP06 pack disk has approximately twice the capacity of 
the RP05. These disks are connected to the system by an MBA. Up to eight 
disk drives can be connected to each MBA. 



3.1.10 RP07 Fixed Media Disk 

The RP07 is a 516 MB, fixed media disk drive that attaches to the MASSBUS 
of the VAX-11/780 system. The RP07 transfers data at 1.3 million bytes per 
second or as an option at a peak rate of 2.2 million bytes per second. The 
nine platters rotate at 3600 rpm and their data is accessed at an average speed 
of 31.3 milliseconds. These disks are connected to the system by an MBA. Up 
to eight disk drives can be connected to each MBA. 


3.1.11 RK06 and RK07 Cartridge Disks 


The RK06 cartridge disk is a removable, random-access, bulk storage device 
with three data surfaces. The RK07 cartridge disk is a double-density RK06. 
The RK06 and RK07 are connected to the system by an RK611 controller that 
interfaces to the UNIBUS adapter. Up to eight disk drives can be connected 
to each RK611. 


3.1.12 RC25 Disk 



The RC25 disk is a self-contained, Winchester-type, mass storage device 
that consists of a disk adapter module, a disk drive, and an integrated disk 
controller. The drive contains two 8-inch, double-sided disks. One of the 
disks (RCF25) is a sealed, nonremovable, fixed-media disk. The other disk 
is a removable cartridge disk that is sealed until it is loaded into the disk 
drive. The disks share a common drive spindle, and together they provide 52 
million bytes of storage. Adapter modules interface the RC25 with either a 
UNIBUS system or with a Q-BUS system. 


3.1.13 RRD50 Read-Only Memory (CDROM) 

The RRD50 is a Compact Disc Read-Only Memory (CDROM) device that uses 
replicated media with a formatted capacity of 600 MB. The RRD50 consists 
of a table-top drive unit and a dual-board Q-BUS controller; the RRD50 
subsystem is a standard disk MSCP device. 


e 
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3.1 Supported Disk Devices and Controllers 


3.1.14 RX01 Console Disk 

The RX01 disk uses a diskette. The disk is connected to the LSI console 
on the VAX-11/780, which the driver accesses using the MTPR and MFPR 
privileged instructions. 

For logical and virtual block I/O operations, data is accessed with one block 
resolution (four sectors). The sector numbers are interleaved to expedite data 
transfers. Section 3.2.5 describes sector interleaving in greater detail. 

For physical block I/O operations, the track, sector, and cylinder parameters 
describe a physical, 128-byte RX01 sector (see Figure 3-1 and Section 3.4). 
Note that the driver does not apply track-to-track skew, cylinder offset, or 
sector interleaving to this physical medium address. 

Figure 3-1 Disk Physical Address 
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3.1.15 RX02 Disk 

The RX02 disk is a mass storage device that uses removable diskettes. The 
RX02 supports existing single-density, RX01-compatible diskettes. A double¬ 
density mode allows diskettes to be recorded at twice the linear density. An 
entire diskette must be formatted in either single or double density. Mixed 
mode diskettes are not allowed. 

The RX02 is connected to the system by an RX211 controller that interfaces 
with the UNIBUS adapter. Up to two disk drives can be controlled by each 
RX211. 

For logical and virtual block I/O operations, data is accessed with single 
block resolution (four single-density sectors or two double-density sectors). 
The sector numbers are interleaved to expedite data transfers. Section 3.2.5 
describes this feature in greater detail. 
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For physical block I/O operations, the track and sector parameters shown in 
Figure 3-1 describe a physical sector (128 bytes in single density; 256 bytes 
in double density). The driver does not apply track-to-track skew, cylinder 
offset, or sector interleaving to the physical medium address. 


3.1.16 TU58 Magnetic Tape (DECtape II) 

The TU58 is a random-access, mass storage magnetic tape device capable 
of reading and writing 256K bytes per drive of data on block-addressable, 
preformatted cartridges at 800 bits per inch. Unlike conventional magnetic 
tape systems, which store information at variable positions on the tape, 
the TU58 stores information at fixed positions on the tape, as do magnetic 
disk or floppy disk devices. Thus, blocks of data can be placed on tape in a 
random fashion, without disturbing previously recorded data. In its physical 
geometry, the tape is conceptually viewed as having one cylinder, four tracks 
per cylinder, and 128 sectors per track. Each sector contains one 512-byte 
block. 

The TU58 uses two vectors. NUMVEC=2 is required on the CONNECT 
command when specifying SYSGEN parameters. 

The TU58 interfaces with the UNIBUS adapter through a DL11-series 
interface device. Both the TU58 and the DL11 should be set to 9600 baud. 
(Because the TU58 is attached to a DL11, the user cannot directly access the 
TU58 registers if the TU58 is on the UNIBUS.) The DIGITAL Terminals and 
Communications Handbook provides additional information on the DL11. The 
TU58, which has its own controller, can access either one or two tape drives. 


3.2 Driver Features 

VMS disk drivers provide the following features: 

• Multiple controllers of the same type (except RB730), for example, more 
than one MBA or RK611 can be used on the system 

• Multiple disk drives per controller (The exact number depends on the 
controller.) 

• Different types of disk drives on a single controller 

• Static dual porting (MBA drives only) 

• Overlapped seeks (except RL02, RX01, RX02, and TU58) 

• Data checks on a per-request, per-file, or per-volume basis (except RX01 
and RX02) 

• Full recovery from power failure for online disk drives with volumes 
mounted 

• Extensive error recovery algorithms, such as error code correction and 
offset (except RB02, RL02, RX01, RX02, and TU58); for DSA disks, these 
algorithms are implemented in the controller 

• Dynamic, as well as static, bad block handling 

• Logging of device errors in a file that can be displayed by field service 
personnel or customer personnel 

• Online diagnostic support for drive level diagnostics 
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• Multiple-block, noncontiguous, virtual I/O operations at the driver level 

• Logical-to-physical sector translation (RX01 and RX02 only) 

The following sections describe the data check, overlapped seek, error 
recovery, and logical-to-physical translation features in greater detail. 


3.2.1 Dual Porting (MASSBUS) 

The VMS MASSBUS disk drivers, DBDRIVER and DRDRIVER, support static 
dual porting. Dual porting allows two MASSBUS controllers to access the 
same disk drive. Figure 3-2 shows this configuration. The RP05, RP06, 
RP07, RM03, RM05, and RM80 disk drives can be ordered, or upgraded in 
the field, with the MASSBUS dual port option. 

Figure 3-2 Dual-Ported Disk Drives 
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3.2.1.1 Port Selection and Access Modes 

The port select switches, on each disk drive, select the ports from which the 
drive can be accessed. A drive can be in one of the following access modes: 

• Locked on Port A—The drive is in a single-port mode (Port A). It does 
not respond to any request on Port B. 

• Locked on Port B—The drive is in a single-port mode (Port B). It does not 
respond to any request on Port A. 

• Programmable A/B—The drive is capable of responding to requests on 
either Port A or Port B. In this mode, the drive is always in one of the 
following states: 

— The drive is connected and responding to a request on Port A. It is 
closed to requests on Port B. 

— The drive is connected and responding to a request on Port B. It is 
closed to requests on Port A. 
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— The drive is in a neutral state. It is equally available to requests on 
either port on a first-come, first-serve basis. 


The operational condition of the drive cannot be changed with the port select 
switches after the drive becomes ready. To change from one mode to another, 
the drive must be in a nonrotating condition. After the new mode selection 
has been made, the drive must be restarted. 


If a drive is in the neutral state and a disk controller either reads or writes 
to a drive register, the drive immediately connects a port to the requesting 
controller. For read operations, the drive remains connected for the duration 
of the operation. For write operations, the drive remains connected until 
a release command is issued by the device driver or a one second timeout 
occurs. After the connected port is released from its controller, the drive 
checks the other port's request flag to determine whether there has been a 
request on that port. If no request is pending, the drive returns to the neutral 
state. 



3.2.1.2 Disk Use and Restrictions 

If the volume is mounted foreign, read/write operations can be performed at 
both ports provided the user maintains control of where information is stored 
on the disk. 

The Autoconfigure Utility currently may not be able to locate the nonactive 
port. For example, if a dual-ported disk drive is connected and responding at 
Port A, the CPU attached to Port B might not be able to find Port B with the 
Autoconfigure Utility. If this problem occurs, execute the 
AUTOCONFIGURE ALL/LOG command after the system is running. 


3.2.1.2.1 Restriction on Dual-Ported Non-DSA Disks in a VAXcluster 

Do not use SYSGEN to AUTOCONFIGURE or CONFIGURE a dual-ported, 
non-DSA disk that is already available on the system through use of an 
MSCP server. Establishing a local connection to the disk when a remote path 
is already known creates two uncoordinated paths to the same disk. Use of 
these two paths may corrupt files and data on any volume mounted on the 
drive. 

Note: If the disk is not dual-ported or is never served by an MSCP server on the 
remote host, this restriction does not apply. 

In a VAXcluster, dual-ported non-DSA disks (MASSBUS or UNIBUS) can be 
connected between two nodes of the cluster. These disks can also be made 
available to the rest of the cluster using the MSCP server on either or both of 
the hosts to which a disk is connected. 

If the local path to the disk is not found during the bootstrap, then the 
MSCP server path from the other host will be the only available access to the 
drive. The local path will not be found during a boot if any of the following 
conditions exist: 

• The port select switch for the drive is not enabled for this host. 

• The disk, cable, or adapter hardware for the local path is broken. 

• There is sufficient activity on the other port to hide the existence of the 
port. 
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• The system is booted in such a way that the SYSGEN 

AUTOCONFIGURE ALL command in the SYS$SYSTEM:STARTUP.COM 
procedure was not executed. 

Use of the disk is still possible through the MSCP server path. 

After the configuration of the disk has reached this state, it is important not 
to add the local path back into the system I/O database. Because the VMS 
operating system does not provide an automatic method for adding this local 
path, the only possible way that you can add this local path is to use the 
Sysgen Utility (SYSGEN) qualifiers AUTOCONFIGURE or CONFIGURE to 
configure the device. SYSGEN is currently not able to detect the presence 
of the disk's MSCP path, and will incorrectly build a second set of data 
structures to describe it. Subsequent events could lead to incompatible and 
uncoordinated file operations, which might corrupt the volume. 

To recover the local path to the disk, it is necessary to reboot the system 
connected to that local path. 

See the VMS VAXcluster Manual for additional information on dual-ported 
disk operation. 


3.2.1.3 Dual-Porting DSA Disks 

Although all DSA disks (see Section 3.2.6) can be dual-ported, only one 
DSA controller (UDA50 or HSC50) can control a disk at a time. These disks 
have a DSA controller connected to each port, but control cannot be shifted 
from one controller to another automatically. However, if one port fails, it is 
possible to access the information on the disk through the other port. Except 
for UDASDs, the VMS operating system automatically switches access to 
the operational port provided the allocation class information has been set 
up correctly (see the VMS VAXcluster Manual) and the volume is mounted 
Files-11 (the volume is not mounted foreign). 


3.2.2 Data Check 


A data check is made after successful completion of a read or write operation 
and, except for the TU58, compares the data in memory with the data on disk 
to make sure they match. 

Disk drivers support data checks at the following levels: 

• Per request—You can specify the data check function modifier 
(IO$M_DATACHECK) on a read logical block, write logical block, read 
virtual block, write virtual block, read physical block, or write physical 
block operation. IO$M_DATACHECK is not supported for the RX01 and 
RX01 drivers. 

• Per volume—You can specify the characteristics "data check all reads" 
and "data check all writes" when the volume is mounted. The VMS DCL 
Dictionary describes volume mounting and dismounting. The VMS System 
Services Reference Manual describes the Mount Volume ($MOUNT) and 
Dismount Volume ($DISMOU) system services. 

• Per file—You can specify the file access attributes "data check on read" 
and "data check on write." File access attributes are specified when the file 
is accessed. Chapter 1 of this manual and the VMS Record Management 
Services Manual describe file access. 
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Offset recovery is performed during a data check but Error Code Correctable 
(ECC) correction is not performed (see Section 3.2.4). For example, if a read 
operation is performed and an ECC correction is applied, the data check 
would fail even though the data in memory is correct. In this case, the driver 
returns a status code indicating that the operation was successfully completed, 
but the data check could not be performed because of an ECC correction. 

Data checks on read operations are extremely rare, and you can either accept 
the data as is, treat the ECC correction as an error, or accept the data but 
immediately move it to another area on the disk volume. 

A data check operation directed to a TU58 does not compare the data in 
memory with the data on tape. Instead, either a read check or a write check 
operation is performed (see Sections 3.4.1 and 3.4.2). 


3.2.3 Overlapped Seeks 

A seek operation involves moving the disk read/write heads to a specific 
place on the disk without any transfer of data. All transfer functions, 
including data checks, are preceded by an implicit seek operation (except 
when the seek is inhibited by the physical I/O function modifier 
IO$M_INHSEEK). Except on RL02, RX01, RX02, TU58 drives, MicroVAX 
2000, VAXstation 2000, or on controllers with floppy disks (for example, 
RQDX3) when the disk is doing I/O, seek operations can be overlapped. 
That is, when one drive performs a seek operation, any number of other 
drives can also perform seek operations. 

During the seek operation, the controller is free to perform transfers on other 
units. Thus, seek operations can also overlap data transfer operations. For 
example, at any one time, seven seeks and one data transfer could be in 
progress on a single controller. 

This overlapping is possible because, unlike I/O transfers, seek operations 
do not require the controller once they are initiated. Therefore, seeks are 
initiated before I/O transfers and other functions that require the controller 
for extended periods. 

All DSA controllers perform extensive seek optimization functions as part of 
their operation; IO$M_INHSEEK has no effect on these controllers. 


3.2.4 Error Recovery 

Error recovery in the VMS operating system is aimed at performing all 

possible operations to complete an I/O operation successfully. Error recovery 

operations fall into the following categories: 

• Handling special conditions such as power failure and interrupt timeout. 

• Retrying nonfatal controller and drive errors. For DSA disks, this function 
is implemented by the controller. 

• Applying error correction information (not applicable for RB02, RL02, 
RX01, RX02, and TU58). For DSA disks, error correction is implemented 
by the controller. 

• Offsetting read heads to try to obtain a stronger recorded signal (not 
applicable for RB02, RL02, RB80, RM80, RX01, RX02, and TU58). For 
DSA disks, this function is implemented by the controller. 
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The error recovery algorithm uses a combination of these four types of error 
recovery operations to complete an I/O operation. 

Power failure recovery consists of waiting for mounted drives to spin up 
and come online, followed by reexecution of the I/O operation that was in 
progress at the time of the power failure. 

Device timeout is treated as a nonfatal error. The operation that was in 
progress when the timeout occurred is reexecuted up to eight times before a 
timeout error is returned. 

Nonfatal controller/drive errors are executed up to eight times before a fatal 
error is returned. 

All normal error recovery procedures (nonspecial conditions) can be inhibited 
by specifying the inhibit retry function modifier (IO$M__INHRETRY). If any 
error occurs and this modifier is specified, the virtual, logical, or physical I/O 
operation is immediately terminated, and a failure status is returned. This 
modifier has no effect on power recovery and timeout recovery. 


3.2.4.1 Skip Sectoring 

Skip sectoring is a bad block treatment technique implemented on R80 disk 
drives (the RB80 and RM80 drives). In each track of 32 sectors, one sector is 
reserved for bad block replacement. Consequently, an R80 drive has available 
only 31 sectors per track. The Get Device/Volume Information ($GETDVI) 
system service returns this value. 

You can detect bad blocks when a disk is formatted. Most formatters 
place these blocks in a bad block file. On an R80 drive, the first bad block 
encountered on a track is designated as a skip sector. This is accomplished 
by setting a flag in the sector header on the disk and placing the block in the 
skip sector file. 

When a skip sector is encountered during a data transfer, it is skipped over, 
and all remaining blocks in the track are shifted by one physical block. For 
example, if block number 10 is a skip sector, and a transfer request was made 
beginning at block 8 for four blocks, then blocks 8, 9, 11, and 12 will be 
transferred. Block 10 will be "skipped." 

Because skip sectors are implemented at the device driver level, they are not 
visible to you. The device appears to have 31 contiguous sectors per track. 
Sector 32 is not directly addressable, although it is accessed if a skip sector is 
present on the track. 


3.2.5 Logical-to-Physical Translation (RX01 and RX02) 

Logical block-to-physical sector translation on RX01 and RX02 drives adheres 
to the standard VMS format. For each 512-byte logical block selected, the 
driver reads or writes four 128-byte physical sectors (or two 256-byte physical 
sectors if an RX02 is in double-density mode). To minimize rotational latency, 
the physical sectors are interleaved. Interleaving allows the processor time to 
complete a sector transfer before the next sector in the block reaches the 
read/write heads. To allow for track-to-track switch time, the next logical 
sector that falls on a new track is skewed by six sectors. (There is no 
interleaving or skewing on read physical block and write physical block 
I/O operations.) Logical blocks are allocated starting at track 1; track 0 is not 
used. 
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The translation procedure, in more precise terms, is as follows: 

1 Compute an uncorrected medium address using the following 
dimensions: 

Number of sectors per track = 26 
Number of tracks per cylinder = 1 
Number of cylinders per disk = 77 

2 Correct the computed address for interleaving and track-to-track skew (in 
that order) as shown in the following VAX FORTRAN statements. ISECT 
is the sector address and ICYL is the cylinder address computed in step 
1: 

Interleaving: 

ITEMP = ISECT*2 

IF (ISECT .GT. 12) ITEMP = ITEMP-25 
ISECT - ITEMP 

Skew: 

ISECT = ISECT+(6*ICYL) 

ISECT = MOD (ISECT, 26) 

3 Set the sector number in the range of 1 through 26 as required by the 
hardware: 

ISECT = ISECT+1 

4 Adjust the cylinder number to cylinder 1 (cylinder 0 is not used): 

ICYL = ICYL+1 



3.2.6 DIGITAL Storage Architecture (DSA) Devices 

The DIGITAL Storage Architecture (DSA) is a collection of specifications that 
cover all aspects of a mass storage product. The specifications are grouped 
into the following general categories: 

• Media format—Describes the structure of sectors on a disk and the 
algorithms for replacing bad blocks 

• Drive-to-controller interconnect—Describes the connection between an 
RA60, RA80, or RA81 drive and its controller 

• Controller-to-host communications—Describes how hosts request 
controllers to transfer data 



Because the VMS operating system supports all DSA disks, it supports all 
controller-to-host aspects of DSA. Some of these disks, such as the RA60, 
RA80, and RA81, use the standard drive-to-controller specifications. Other 
disks, such as the RC25, RD51, RD52, RD53, and RX50, do not. Disk systems 
that use the standard drive-to-controller specifications employ the same 
hardware connections and use the HSC50 and UDA50 interchangeably. 

Disk systems that do not use the drive-to-controller specifications provide 
their own internal controller, which conforms to the controller-to-host 
specifications. 
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DSA disks differ from MASSBUS and UNIBUS disks in the following ways: 

• DSA disks contain no bad blocks. The hardware and the disk class driver 
(DUDRIVER) function to ensure a logically contiguous range of good 
blocks. If any block in the user area of the disk develops a defective 
area, all further access to that block is revectored to a spare good block. 
Consequently, it is never necessary to run the Bad Block Locator Utility 
(BAD) on DSA disks. There is no manufacturer's bad block list and the 
file BADBLK.SYS is empty. (The Verify Utility, which is invoked by the 
ANALYZE /DISK-STRUCTURE /READ_CHECK command, can be 
used to check the integrity of newly received disks.) See Section 3.2.6.1 
for additional information about bad block replacement for DSA disks. 

• Insert a WAIT statement in your SYSTARTUP_V50.COM file prior to the 
first MOUNT statement for a DSA disk. The wait period should be about 
two to four seconds for the UDA50 and about 30 seconds for the HSC50. 
The wait time is controller-dependent and can be as much as several 
minutes if the controller is offline or otherwise inoperative. If this wait is 
omitted, the MOUNT request may fail with a "no such device" status. 

• The DUDRIVER and the DSA device controllers allow multiple, 
concurrently outstanding QIO requests. The order in which these requests 
complete might not be in the order in which they were issued. 

• All DSA disks can be dual-ported, but only one HSC/UDA controller 
can control a disk at a time (see Section 3.2.1.3). DSA disks that use an 
internal controller cannot be dual-ported. 

• In many cases, you can attach a DSA disk to its controller on a running 
VMS operating system and then use it immediately without manual 
intervention. 

• DSA disks and the DUDRIVER do not accept physical QIO data transfers 
or seek operations. 


3.2.6.1 Bad Block Replacement and Forced Errors for DSA Disks 

Disks that are built according to the DSA specifications appear to be error 
free. Some number of logical blocks are always capable of recording data. 
When a disk is formatted, every user-addressable logical block is mapped to 
a functioning portion of the actual disk surface, which is known as a physical 
block. The physical block has the true data storage capacity represented by 
the logical block. 

Additional physical blocks are set aside to replace blocks that fail during 
normal disk operations. These extra physical blocks are called replacement 
blocks. Whenever a physical block to which a logical block is mapped begins 
to fail, the associated logical block is remapped (revectored) to one of the 
replacement blocks. The process that revectors logical blocks is called a 
badblock replacement operation. Bad block replacement operations use data 
stored in a special area of the disk called the Replacement and Caching 
Table (RCT). 

When a drive-dependent error threshold is reached, the need for a bad block 
replacement operation is declared. Depending on the controller involved, the 
bad block replacement operation is performed either by the controller itself 
(as is the case with HSCs) or by the host (as is the case with UDAs). In either 
case, the same steps are performed. After inspecting and altering the RCT, 
the failing block is read and its contents are stored in a reserved section of the 
RCT. 
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The design goal of DSA disks is that this read operation proceeds without 
error and that the RCT copy of the data is correct (as it was originally written). 
The failing block is then tested with one or more data patterns. If no errors 
are encountered in this test, the original data is copied back to the original 
block and no further action is taken. If the data-pattern test fails, the logical 
block is revectored to a replacement block. After the block is revectored, the 
original data is copied back to the revectored logical block. In all these cases, 
the original data is preserved and the bad block replacement operation occurs 
without the user being aware that it happened. 

However, if the original data cannot be read from the failing block, a best 
attempt copy of the data is stored in the RCT and the bad block replacement 
operation proceeds. When the time comes to write-back the original data, 
the best attempt data (stored in the RCT) is written back with the forced error 
flag set. The forced error flag is a signal that the data read is questionable. 
Reading a block that contains a forced error flag causes the status SS$__ 
FORCEDERROR to be returned. This status is displayed by the following 
message: 

# /,SYSTEM-F-FORCEDERROR, forced error flagged in last sector read 

Writing into a block always clears the forced error flag. 

Note that most VMS utilities and DCL commands treat the forced error flag as 
a fatal error and terminate operation when they encounter it. However, the 
Backup Utility (BACKUP) continues to operate in the presence of most errors, 
including the forced error. BACKUP continues to process the file, and the 
forced error flag is lost. Thus, data that was formerly marked as questionable 
may become "correct" data. 

System managers (and other users of BACKUP) should assume that forced 
errors reported by BACKUP signal possible degradation of the data. 

To determine what, if any, blocks on a given disk volume have the forced 
error flag set, use the ANALYZE /DISK_STRUCTURE /READ_CHECK 
command, which invokes the Verify Utility. The Verify Utility reads every 
logical block allocated to every file on the disk and then reports (but ignores) 
any forced error blocks encountered. 


3.2.7 VAXstation 2000 and MicroVAX 2000 Disk Driver 

The VAXstation 2000 and MicroVAX 2000 disk driver supports some DSA 
disk operation. In particular, the driver supports block revectoring and bad 
block replacement. This provides the system with a logically perfect disk 
medium. 

Like other DSA disks, if a serious error occurs during a replacement operation, 
the disk is write-locked to prevent further changes. This is done to preserve 
data integrity and minimize damage that could be caused by failing hardware. 
Unlike other DSA disks, there is no visible indication on the drive itself 
that the disk is write-locked. However, the following indicators help you 
determine that the disk has become write-protected: 

• ERRFMT messages show that the disk is write-locked. 

• The disk enters mount verification and hangs. 

• DCL command SHOW DEVICE output shows that the disk is write- 
locked. 


3-15 





Disk Drivers 

3.2 Driver Features 

• Error messages from programs and utilities attempting to write to the 
disk. 

If the disk becomes write-locked, you should use the following procedure: 

1 Shut down the system. 

2 Use standalone BACKUP to create a full backup of the disk. 

3 Format the disk with the disk formatter. 

4 Restore the disk from the backup using standalone BACKUP. Note that 
any files with sectors flagged with a forced error may be corrupted and 
may need to be restored from a previous backup. 

If errors occurring during replacement operations persist, call DIGITAL Field 

Service. 


3.3 Device Information 

You can obtain information on all disk device characteristics by using the Get 
Device/Volume Information ($GETDVI) system service (see the VMS System 
Services Reference Manual). 

$GETDVI returns disk characteristics when you specify the item codes 
DVI$_DEVCHAR and DVI$_DEVCHAR2. Table 3-2 lists the possible 
characteristics for disk devices. 


Table 3-2 Disk Device Characteristics 


Characteristic 1 

Meaning 


Dynamic Bits (Conditionally Set) 

DEV$M_AVL 

Device is online and available. 

DEV$M_CDP 2 

Dual-path device with two UCBs. 

DEV$M_CLU 2 

Device is available clusterwide. 

DEV$M_2P 2 

Device is dual-pathed. 

DEV$M_FOR 

Device is foreign. 

DEV$M_MNT 

Volume is mounted. 

DEV$M_RCK 

Perform data check all reads. 

DEV$M_WCK 

Perform data check all writes. 

DEV$M_MSCP 2 

Device is accessed using the mass storage control 
protocol. 

DEV$M_RCT 

Disk contains Replacement and Caching Table. 

DEV$M_SRV 2 

For a VAXcluster, device is served by the MSCP 
server. 


'Defined by the SDEVDEF macro 

2 These bits are located in DVI$_DEVCHAR2. 
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Table 3-2 (Cont.) 

Disk Device Characteristics 

Characteristic 1 

Meaning 

Static Bits (Always Set) 

DEV$M_FOD 

DEV$M_IDV 

DEV$M_ODV 

DEV$M_RND 

DEV$M_SHR 

Device is file-oriented. 

Device is capable of input. 

Device is capable of output. 

Device is capable of random access. 

Device is shareable. 

defined by the $DEVDEF macro 


DVI$_DEVBUFSIZ returns the buffer size. The buffer size is the default to be 
used for disk transfers (this default is normally 512 bytes). DVI$_DEVTYPE 
and DVI$_DEVCLASS return the device type and class names, which are 
defined by the $DCDEF macro. The disk model determines the device type. 
For example, the device type for the RA81 is DT$_RA81. (Foreign device 
types take the form DT$_FD1 through DT$_FD8.) The device class for disks 
is DC$_DISK. 

DVI$_CYLINDERS returns the number of cylinders per volume (that is, per 
disk), DVI$_TRACKS returns the number of tracks per cylinder, and 
DVI$_SECTORS returns the number of sectors per track. Values are returned 
as four-byte decimal numbers. 

DVI$_MAXBLOCK returns the maximum number of blocks (1 block = 512 
bytes) that can be contained on the volume (that is, on the disk). Values are 
returned as four-byte decimal numbers. This information can be used, for 
example, to determine the density of an RX02 diskette (single density = 494 
blocks, double density = 988 blocks). 


3.4 Disk Function Codes 

VMS disk drivers can perform logical, virtual, and physical I/O functions. 
Foreign-mounted devices do not require privilege to perform logical and 
virtual I/O requests. 

Logical and physical I/O functions allow access to volume storage and require 
only that the issuing process have access to the volume. However, DSA disks 
and the disk class driver (DUDRIVER) do not accept physical QIO data 
transfers or seek operations. 

Note: The results of logical and physical I/O operations are unpredictable if 
an ancillary control process (ACP) or extended QIO processing (XQP) is 
present. 

Virtual I/O functions require an ACP for Files-11 On-Disk Structure Level 1 
files or an XQP for Files-11 On-Disk Structure Level 2 files. Virtual I/O 
functions must be executed in a prescribed order. First, you create and access 
a file, then you write information to that file, and lastly you deaccess the file. 
Subsequently, when you access the file, you read the information, and then 
deaccess the file. Delete the file when the information is no longer useful. 
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Non-DSA disk devices can read or write up to 65,535 bytes in a single 
request. DSA devices connected to an HSC50 can transfer up to 4 billion 
bytes in a single request. In all cases, the maximum size of the transfer is 
limited by the number of pages that can be faulted into the process's working 
set, and then locked into physical memory. (The disk driver is responsible 
for any memory management functions of this type.) The size of the transfer 
does not affect the applicable quotas (direct I/O count, buffered I/O count, 
and AST count limit). These quotas refer to the number of outstanding I/O 
operations of each type, not the size of the I/O operation being performed. 

The volume to which a logical or virtual function is directed must be mounted 
for the function actually to be executed. If it is not mounted, either a "device 
not mounted" or "invalid volume" status is returned in the I/O status block. 

Table 3-3 lists the logical, virtual, and physical disk I/O functions and their 
function codes. Chapter 1 describes the QIO level interface to the disk device 
ACP. 


Table 3-3 Disk I/O Functions 


Function Code and 
Arguments 

Type 1 

Function 

Modifiers 

Function 

IO$_CREATE P1,[P2],- 
[P3],[P4],[P5] 

V 

IO$M_CREATE 
IO$M_ACCESS 
IO$M—DELETE 

Create a directory entry or a file. 

IO$_ACCESS PI, [P2],- 
[P3],[P4],[P5] 

V 

IO$M_CREATE 
IO$M_ACCESS 

Search a directory for a specified file and 
access the file if found. 

IO$_DEACCESS P1,[P2],- 
[P3],[P4],[P5] 

V 


Deaccess a file, and if specified, write final 
attributes in the file header. 

IO$_MODIFY P1,[P2], - 
[P3],[P4],[P5] 

V 


Modify the file attributes or allocation, or 
both. 

IO$_DELETE PI,[P2],- 
[P3],[P4],[P5] 

V 

IO$M_DELETE 

Remove a directory entry or file header, or 
both. 

IO$_ACPCONTROL P1,- 
[P2],[P3],[P4],[P5] 

V 

IO$M_DMOUNT 

Perform miscellaneous control functions. 

IO$_READVBLK P1,P2,P3 

V 

IO$M_ 

DATACHECK 2 

IO$M_INHRETRY 

Read virtual block. 

IO$_READLBLK P1,P2,P3 

L 

IO$M_ 

DATACHECK 2 

IO$M_INHRETRY 

Read logical block. 

IO$_READPBLK P1,P2,P3 

P 

IO$M_ 
DATACHECK 2 
IO$M_INHRETRY 
IO$M_INHSEEK 3 

Read physical block. 5 


1 V = virtual; L = logical; P = physical 


2 Not for RX01 and RX02 
3 Not for TU58, RX01, RX02, RB02, and RL02 
5 Not for DSA disks 
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Table 3-3 (Cont.) Disk I/O Functions 


Function Code and 
Arguments 

Type 1 

Function 

Modifiers 

Function 

IO$_WRITEVBLK P1,P2,P3 

V 

IO$M_ 

DATACHECK 2 

IO$M_ERASE 

IO$M_INHRETRY 

Write virtual block. 

IO$_WRITELBLK P1,P2,P3 

L 

IO$M_ 

DATACHECK 2 

IO$M_ERASE 

IO$M_INHRETRY 

Write logical block. 

IO$_WRITEPBLK P1,P2,P3 

P 

IO$M_ 

DATACHECK 2 

IO$M_ERASE 

IO$M_INHRETRY 

IO$M_INHSEEK 3 

IO$M _DELD AT A 4 

Write physical block. 5 

IO$_WRITECHECK PI 

P2,P3 

IO$_SENSEMODE 

P 

L 


Verify data written to disk by a previous 
write QIO. 2 

Sense the device-dependent characteristics 
and return them in the I/O status block. 

IO$_SENSECHAR 

P 


Sense the device-dependent characteristics 
and return them in the I/O status block. 

IO$_FORMAT PI 

IO$_SEARCH PI 

P 

P 


Set density (RX02 only). 

Search for specified block or sector (only 
for TU58). 

IO$_PACKACK 

P 


Update UCB fields if RX02; initialize volume 
valid on other devices. Bring DSA units 
online. 

IO$_AVAILABLE 

P 


Clear volume valid; make DSA units 
available. 

IO$_UNLOAD 

P 


Clear volume valid; make DSA units 
available and spin down the volume. 

IO$SEEK PI 

P 


Seek to specified cylinder. 5 


’V = virtual; L = logical; P = physical 


2 Not for RX01 and RX02 
3 Not for TU58, RX01, RX02, RB02, and RL02 
4 RX02 only 
5 Not for DSA disks 


The function-dependent arguments for IO$—CREATE, IO$—ACCESS, 
IO$_DEACCESS, IO$_MODIFY, and IO$_DELETE are as follows: 

• pi—The address of the file information block (FIB) descriptor. 

• p2—The address of the file name string descriptor (optional). If specified, 
the name is entered in the directory specified by the FIB. 

• P 3 —The address of the word that is to receive the length of the resulting 
file name string (optional). 


3-19 












Disk Drivers 

3.4 Disk Function Codes 


• P4—The address of a descriptor for a buffer that is to receive the resulting 
file name string (optional). 

• P5—The address of a list of attribute descriptors (optional). If specified, 
the indicated attributes are read (IO$_ACCESS) or written (IO$_CREATE, 
IO$_DEACCESS, and IO$_MODIFY). 

See Chapter 1 for more information on these functions. 

The function-dependent arguments for IO$_READVBLK, IO$_READLBLK, 

IO$_WRITEVBLK, and IO$_WRITELBLK are as follows: 

• PI—The starting virtual address of the buffer that is to receive the data 
from a read operation; or, in the case of a write operation, the virtual 
address of the buffer that is to be written on the disk. 

• P2—The number of bytes that are to be read from the disk, or written 
from memory to the disk. An even number must be specified if the 
controller is an RK611, RL11, RX211, or UDA50. 

• P3—The starting virtual/logical disk address of the data to be transferred 
in a read operation; or, in a write operation, the disk address of the area 
that is to receive the data. 

In a virtual read or write operation, the address is expressed as a block 
number within the file, that is, block 1 of the file is virtual block 1. 
(Virtual block numbers are converted to logical block numbers using 
mapping windows that are set up by the file system ACP process.) 

In a logical read or write operation, the address is expressed as a block 
number relative to the start of the disk. For example, the first sector on 
the disk contains block 0 (or at least the beginning of block 0). 

The function-dependent arguments for IO$_WRITEVBLK, IO$_WRITELBLK, 

and IO$_WRITEPBLK functions that include the IO$M_ERASE function 

modifier are as follows: 

• PI—The starting virtual address of the buffer that contains a four-byte, 
user-specified erase pattern. If the PI address is 0, a longword of 0 will 
be used for the erase pattern. If the PI address is nonzero, the contents 
of the four bytes starting at that address will be used as the erase pattern. 
DIGITAL recommends that the user specify a PI address of 0 to lower 
system overhead. 

Note: DSA disk controllers provide controlled, assisted erasing for the 

IO$M—ERASE modifier (with virtual and logical write functions) only 
when the erase pattern is all Os. If a nonzero erase pattern is used, 
there is a significant performance degradation with these disks. DSA 
disks do not accept physical QIO transfers. 

• P2—The number of bytes of erase pattern to write to the disk. The 
number specified is rounded up to the next highest block boundary (512 
bytes). 

• P3—The starting virtual, logical, or physical disk address of the data to 
be erased. 


3-20 








Disk Drivers 

3.4 Disk Function Codes 


The function-dependent arguments for IO$_WRITECHECK, 

IO$_READPBLK, and IO$_WRITEPBLK are as follows: 

• pi—The starting virtual address of the buffer that is to receive the data 
in a read operation; or, in a write operation, the starting virtual address of 
the buffer that is to be written on the disk. Passed by reference. 

• p 2 —The number of bytes that are to be read from the disk, or written 
from memory to the disk. Passed by value. An even number must be 
specified if the controller is an RK611, RL11, or UDA50. 

• P 3 —The starting physical disk address of the data to be read in a read 
operation; or, in a write operation, the starting physical address of 

the disk area that is to receive the data. Passed by value. The address is 
expressed as sector, track, and cylinder in the format shown in Figure 3-3. 
(On the RX01 and RX02, the high word specifies the track number rather 
than the cylinder number.) Check the UCB of a currently mounted device 
to determine the maximum physical address value for that type of device. 

Note: On the RB80 and RM80, do not address cylinders 560 and 561. These 
two cylinders are used for diagnostic testing only. 

The function-dependent argument for IO$_SEARCH is as follows: 

• pi—The physical disk address where the tape is positioned. The 
address is expressed as sector, track, and cylinder in the format shown in 
Figure 3-3. 


Figure 3-3 Starting Physical Address 



(except RX01 and RX02) 



31 


16 

15 


0 

P3: 

track 

sector 




(RX01 and RX02 only) 


ZK-652-82 


The function-dependent argument for IO$_SEEK is as follows: 

• pi—The physical cylinder number where the disk heads are positioned. 

The address is expressed in the format shown in Figure 3-4. 
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Figure 3-4 Physical Cylinder Number Format 



The function dependent argument for IO$_FORMAT is as follows: 

• PI—The density at which an RX02 diskette is reformatted (see 

Section 3.4.4). 


3.4.1 Read 

The read function reads data into a specified buffer from disk starting at a 
specified disk address. 

The VMS operating system provides the following read function codes: 

• IO$_READVBLK—Read virtual block 

• IO$_READLBLK—Read logical block 

• IO$_READPBLK—Read physical block 

If a read virtual block function is directed to a volume that is mounted 
foreign, that function is converted to read logical block. If a read virtual block 
function is directed to a volume that is mounted structured, the volume is 
handled in the same way as for a file-structured device. 

Three function-dependent arguments are used with these codes: PI, P2, and 
P3. These arguments are described in Section 3.4. 

The data check function modifier (IO$M_DATACHECK) can be used with 
all read functions. If this modifier is specified, a data check operation is 
performed after the read operation completes. A data check operation is 
also performed if the volume that has been read, or the volume on which 
the file resides (virtual read), has the characteristic "data check all reads." 
Furthermore, a data check is performed after a virtual read if the file has the 
attribute data check on read." The RX01 and RX02 drivers do not support the 
data check function. 

If IO$M_DATACHECK is specified with a read function code to a TU58, or 
if the volume read has the characteristic "data check all reads," a read check 
operation is performed. This alters certain TU58 hardware parameters when 
the tape is read. (The read threshold in the data recovery circuit is increased; 
if the tape has any weak spots, errors are detected.) 

The data check function modifier to a disk or tape can return five error codes 
in the I/O status block: 

SS$_CTRLERR SS$_DRVERR SS$_MEDOFL 
SS$_NONEXDRV SS$_NORMAL 

If no errors are detected, the disk or tape data is considered reliable. 
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The inhibit retry function modifier (IO$M—INHRETRY) can be used with all 
read functions. If this modifier is specified, all error recovery attempts are 
inhibited. IO$M —INHRETRY takes precedence over IO$M_DATACHECK. If 
both are specified and an error occurs, there is no attempt at error recovery 
and no data check operation is performed. If an error does not occur, the data 
check operation is performed. 


3.4.2 Write 

The write function writes data from a specified buffer to disk starting at a 
specified disk address. 

The VMS operating system provides the following write function codes: 

• IO$_WRITEVBLK—Write virtual block 

• IO$_WRITELBLK—Write logical block 

• IO$_WRITEPBLK—Write physical block 

If a write virtual block function is directed to a volume that is mounted 
foreign, the function is converted to write logical block. If a write virtual 
block function is directed to a volume that is mounted structured, the volume 
is handled in the same way as for a file-structured device. 

Three function-dependent arguments are used with these codes: PI, P2, and 
P3. These arguments are described in Section 3.4. 

The data check function modifier (IO$M_DATACHECK) can be used with 
all write operations. If this modifier is specified, a data check operation is 
performed after the write operation completes. A data check operation is 
also performed if the volume written, or the volume on which the file resides 
(virtual write), has the characteristic "data check all writes." Furthermore, a 
data check is performed after a virtual write if the file has the attribute "data 
check on write." The RX01 and RX02 drivers do not support the data check 
function. 

If IO$M_DATACHECK is specified with a write function code to a TU58, or 
if the volume written has the characteristic "data check all writes," a write 
check operation is performed. The write check verifies data written on the 
tape. First, the specified data is written on the tape. Then the tape is reversed 
and the TU58 controller reads the data internally to perform a checksum 
verification. If the checksum verification is unsuccessful after eight attempts, 
the write check operation is aborted and an error status is returned. 

The inhibit retry function modifier (IO$M_INHRETRY) can be used with all 
write functions. If that modifier is specified, all error recovery attempts are 
inhibited. IO$M —INHRETRY takes precedence over IO$M_DATACHECK. If 
both IO$M_INHRETRY and IO$M_DATACHECK are specified and an error 
occurs, there is no attempt at error recovery, and no data check operation is 
performed. If an error does not occur, the data check operation is performed. 
IO$M_INHRETRY has no affect on DSA disks. 

The write deleted data function modifier (IO$M _DELDATA) can be used 
with the write physical block (IO$_WRITEPBLK) function to the RX02. If this 
modifier is specified, a deleted data address mark instead of the standard data 
address mark is written preceding the data. Otherwise, the operation of the 
IO$_WRITEPBLK function is the same; write data is transferred to the disk. 
When a successful read operation is performed on this data, the status code 
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SS$_RDDELDATA is returned in the I/O status block rather than the usual 
SS$_NORMAL status code. 

The IO$M_ERASE function modifier can be used with all write function 
codes to erase a user-selected part of a disk. This modifier propagates an 
erase pattern through the specified range. Section 3.4 describes the write 
function arguments to be used with IO$M—ERASE. 


3.4.3 Sense Mode 

Sense mode operations obtain current disk device-dependent characteristics 
that are returned to the caller in the second longword of the I/O status block 
(see Figure 3-6). The VMS operating system provides the following function 
codes: 

• IO$_SENSEMODE—Sense characteristics 

• IO$_SENSECHAR—Sense characteristics 

IO$—SENSEMODE is a logical function. IO$_SENSECHAR is a physical I/O 

function and requires the access privilege necessary to perform physical I/O. 
No device- or function-dependent arguments are used with either function. 


3.4.4 Set Density 

The set density function assigns a new density to an entire RX02 floppy 
diskette. The diskette is also reformatted: new data address marks are written 
(single or double density) and all data fields are zeroed. Set density is a 
physical I/O function and requires the access privilege necessary to perform 
physical I/O. The following function code is provided: 

• IO$_FORMAT 

IO$_FORMAT takes the following function-dependent argument: 

• PI—The density at which the diskette is reformatted: 

0 = single density (default) 

1 = single density 

2 = double density 

The set density operation should not be interrupted before it is completed 
(about 15 seconds). If the operation is interrupted, the resulting diskette 
might contain illegal data address marks in both densities. The diskette must 
then be completely reformatted and the function reissued. 
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3.4.5 Search 

The search function positions a TU58 magnetic tape to the block specified. 
Search is a physical I/O function and requires the access privilege necessary 
to perform physical I/O. The VMS operating system provides a single 
function code: 

• IO$_SEARCH 

This function code takes the following function-dependent argument: 

• pi—Specifies the block where the read/write head will be positioned. 
The low byte contains the sector number in the range 0 to 127; the high 
byte contains the track number in the range 0 to 3. 

IO$_SEARCH can save time between read and write operations. For 
example, nearly 30 seconds are required to completely rewind a tape. If 
the last read or write operation is near the end of the tape and the next 
operation is near the beginning of the tape, the search operation can begin 
after the last operation completes, and the tape will rewind while the process 
is otherwise occupied. (The search QIO is not completed until the search is 
completed. Consequently, if a $QIOW system service request is issued, the 
process will be held up until the search is completed.) 


3.4.6 Pack Acknowledge 

The pack acknowledge function sets the volume valid bit for all disk devices. 
Pack acknowledge is a physical I/O function and requires the access privilege 
to perform physical I/O. If directed to an RX02 drive, pack acknowledge 
also determines the diskette density and updates the device-dependent 
information returned by $GETDVI item codes DVI$—CYLINDERS, DVI$— 
TRACKS, DVI$_SECTORS, DVI$_DEVTYPE, DVI$_CLASS, and DVI$_ 
MAXBLOCK. If directed to a DSA disk, pack acknowledge also sends the 
online packet to the controller. The following function code is provided: 

• IO$_PACKACK 

This function code takes no function-dependent arguments. 

IO$_PACKACK must be the first function issued when a volume (pack, 
cartridge, or diskette) is placed in a disk drive. IO$_PACKACK is issued 
automatically when the DCL commands INITIALIZE or MOUNT are issued. 

For DSA disks, the IO$_PACKACK function involves at least one disk read 
and four disk writes. It also locks the drive's port selector on the port that 
initiated the pack acknowledge function. 


3.4.7 Unload 


The unload function clears the volume valid bit for all disk drives, makes 
DSA disks available, and issues an unload command to the drive (spins down 
the volume). The unload function reverses the function performed by pack 
acknowledge (see Section 3.4.6). The following function code is provided. 

• IO$_UNLOAD 

This function takes no function-dependent arguments. 
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3.4.8 Available 

The available function clears the volume valid bit for all disk drives; that is, 
it reverses the function performed by pack acknowledge (see Section 3.4.6). 
No unload function is issued to the drive. Therefore, those drives capable of 
spinning down do not spin down. The following function code is provided: 

• IO$_AVAILABLE 

This function takes no function-dependent arguments. 

3.4.9 Seek 

The seek function directs the read/write heads to move to the cylinder 
specified in the PI argument (see Sections 3.2.3 and 3.4, and Figure 3-4). 

3.4.10 Write Check 

The write check function verifies that data was written to disk correctly. The 
data to be checked is addressed using physical disk addressing (sector, track, 
and cylinder) (see Figure 3-3). If the request is directed to a DSA disk, you 
must specify a logical block number, even though IO$_WRITECHECK is a 
physical I/O function. The following function code is provided: 

• IO$_WRITECHECK 

A write QIO must be used to write data to disk before you enter this 
command. IO$_WRITECHECK then reads the same block of data and 
compares it with the data in the specified buffer. Three function-dependent 
arguments are used with this code: PI, P2, and P3. These arguments are 
described in Section 3.4. 

—WRITE CHECK is similar to the IO$M_DATACHECK function modifier 
for write QIOs, except that IO$_WRITECHECK does not write the data 
to disk; it is specified after data is written by a separate write QIO. 
Nonprivileged processes can use the IO$M_DATACHECK modifier with 
IO$_WRITEVBLK (which does not require access privilege) to determine 
whether data is written correctly. The RX01 and RX02 drivers do not support 
the write check function. 

The write check function and the data check function modifier to a TU58 can 
return six error codes in the I/O status block: SS$_NORMAL, 

SS$_CTRLERR, SS$_DRVERR, SS$_MEDOFL, SS$_NONEXDRV, and 
SS$_WRTLCK. 
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Figure 3—5 IOSB Contents 



3.5 I/O Status Block 

Figure 3-5 shows the I/O status block (IOSB) for all disk device QIO 
functions except Sense Mode. Figure 3-6 shows the I/O status block for 
the Sense Mode function. Appendix A lists the status messages for all 
functions and devices. (The VMS System Messages and Recovery Procedures 
Reference Volume provides explanations and suggested user actions for these 
messages.) 

The byte count is a 32-bit integer giving the actual number of bytes 
transferred to or from the process buffer. 

The second longword of the I/O status block for the Sense Mode function 
returns information on the cylinder, track, and sector configuration for the 
particular device. 


3.6 Programming Example 

This sample program (Example 3-1) provides an example of optimizing 
access time to a disk file. The program creates a file using VMS RMS, 
stores information concerning the file, and closes the file. The program then 
accesses the file and reads and writes to the file using the Queue I/O ($QIO) 
system service. 
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Example 3-1 Disk Program Example 


• ******************************************************************** 


.TITLE Disk Driver Programming Example 
.IDENT /01/ 


Define necessary symbols. 

SFIBDEF ;Define file information block Offsets 

$I0DEF ;Define I/O function codes 

$RMSDEF ;Define RMS-32 Return Status Values 

Local storage 

Define number of records to be processed. 


NUM_RECS=100 


;0ne hundred records 


Allocate storage for necessary data structures. 

Allocate File Access Block. 

A file access block is required by RMS-32 to open and close a 
file. 


FAB.BLOCK: 

$FAB ALQ = 100,- 

FAC = PUT,- 
FNA = FILE.NAME,- 
FNS = FILE.SIZE,- 
FOP = CTG,- 
MRS = 512,- 

NAM = NAM.BLOCK,- 
ORG = SEQ,- 

REM = FIX 

; Allocate file information block. 


;Initial file size is to be 
;100 blocks 

;File Access Type is output 
;File name string address 
;File name string size 
;File is to be contiguous 
;Maximum record size is 512 
;bytes 

;File name block address 
;File organization is to be 
;sequential 

;Record format is fixed length 


; A file information block is required as an argument in the 

; Queue I/O system service call that accesses a file. 

FIB.BLOCK: ; 

.BLKB FIB$K_LENGTH \ 


Allocate file information block descriptor. 


FIB.DESCR: ; 

.LONG FIB$K.LENGTH ;Length of the file 

;information block 

.LONG FIB.BLOCK ;Address of the file 

;information block 
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Example 3-1 (Cont.) Disk Program Example 


Allocate File Name Block 

A file name block is required by RMS-32 to return information 
concerning a file (for example, the resultant file name string 
after logical name translation and defaults have been applied). 


NAM.BLOCK: 

$NAM 


Allocate Record Access Block 


A record access block is required by RMS-32 for record 
operations on a file. 


RAB.BLOCK: 

$RAB FAB = FAB.BLOCK,- 
RAC = SEQ,- 

RBF = RECORD.BUFFER,- 
RSZ = 512 


;File access block address 
;Record access is to be 
;sequential 

;Record buffer address 
;Record buffer size 


Allocate direct address buffer 


BLOCK.BUFFER: 

.BLKB 1024 


;Direct access buffer is 1024 
;bytes 


; Allocate space to store channel number returned by the $ASSIGN 
; Channel system service. 

DEVICE.CHANNEL: ; 

.BLKW 1 ; 


Allocate device name string and descriptor. 


DEVICE.DESCR: 

.LONG 20$-10$ 
.LONG 10$ 

10$: .ASCII /SYS$DISK/ 

20 $: 


Length of device name string 
Address of device name string 
Device on which created file 
will reside 

Reference label to calculate 
length 


Allocate file name string and define string length symbol. 


FILE.NAME: 

.ASCII /SYS$DISK:MYDATAFIL.DAT/ 
FILE SIZE=.-FILE.NAME 


;File name string 
File name string length 


Allocate I/O status quadword storage. 


Example 3-1 Cont'd. on next page 
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Example 3-1 (Cont.) Disk Program Example 


IO.STATUS: 

.BLKQ 1 

; Allocate output record buffer. 


RECORD.BUFFER: 

.BLKB 512 


;Record buffer is 512 bytes 


******************************************************************** 


Start Program 

***************** ++ * +++J|C3)e+sk3|C5|c+5)ej|cs|c+3|c+s|CJ|e5|C5(t3|e+sjC3jc+5|c+5|ej|e3je3je+s|C5|C5je5je3je5|cHcj|ejJejjejjc3|c3|t5|c}|cj|c 


The purpose of the program is to create a file called MYDATAFIL.DAT 
using RMS-32; store information concerning the file; write 100 
records, each containing its record number in every byte; 
close the file; and then access, read, and write the file directly, 
using the Queue I/O system service. If any errors are detected, the 
program returns to its caller with the final error status in 
register RO. 

.ENTRY DISK_EXAMPLE,~M<R2,R3,R4,R5,R6> ;Program starting 

;address 


First create the file and open it, using RMS-32. 

;First part of example 
;Create and open file 
;If low bit = 0, creation 
;failure 


PART_1: 

$CREATE FAB = FAB.BLOCK 
BLBC RO,20$ 


Second, connect the record access block to the created file. 

$C0NNECT RAB = RAB_BL0CK ;Connect the record access 

;block 

BLBC R0,30$ ;if low bit = 0, creation 

;failure 

Now write 100 records, each containing its record number. 


MOVZBL #NUM_RECS,R6 ;Set record write loop count 

; Fill each byte of the record to be written with its record number. 

10$: SUBB3 R6,#NUM_RECS+1,R5 ;Calculate record number 

M0VC5 #0,(R6),R5,#512,RECORD.BUFFER ;Fill record buffer 

; Now use RMS-32 to write the record into the newly created file. 


Example 3—1 Cont'd. on next page 
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Example 3-1 (Cont.) Disk Program Example 


$PUT RAB = RAB_BL0CK ;Put record in file 

BLBC R0,30$ ;If low bi't = 0» P u-t failure 

SOBGTR R6,10$ ;Any more records to write? 

The file creation part of the example is almost complete. All that 
remains to be done is to store the file information returned by 
RMS-32 and close the file. 

NAM_BLOCK+NAM$W_FID,FIB_BLOCK+FIB$W_FID ;Save file 

;identification 

NAM_BL0CK+NAM$W_FID+2,FIB_BL0CK+FIB$W_FID+2 ;Save 

;sequence number 

NAM_BL0CK+NAM$W_FID+4,FIB_BL0CK+FIB$W_FID+4 ;Save 

;relative volume 

FAB = FAB.BLOCK ;Close file 

R0,PART_2 ;If low bit set, successful 

;close 

;Return with RMS error status 


MOVW 

MOVW 

MOVW 

$CL0SE 

BLBS 

20$ RET 


Record stream connection or put record failure. 


; Close file and return status. 

30$: PUSHL RO 

$CL0SE FAB = FAB.BLOCK 

POPL RO 

RET 


;Save error status 
;Close file 

;Retrieve error status 
;Return with RMS error status 


The second part of the example illustrates accessing the previously 
created file directly using the Queue I/O system service, randomly 
reading and writing various parts of the file, and then deaccessing 
the file. 


• First, assign a channel to the appropriate device and access the 
; file. 

PART.2: • 

$ASSIGN_S DEVNAM = DEVICE.DESCR,- ;Assign a channel to file 

CHAN = DEVICE.CHANNEL ;device 
BLBC RO,20$ ;If low bit = 0, assign 

;failure 

MOVL #FIB$M_NOWRITE!FIB$M_WRITE,- ;Set for read/write 
FIB_BLOCK+FIB$L_ACCTL ;access 
$QI0W_S CHAN = DEVICE.CHANNEL,- ;Access file on device channel 
FUNC = #I0$_ACCESS!IO$M_ACCESS,- ;I/0 function is 

;access file 

I0SB = IO.STATUS,- ;Address of I/O status 

;quadword 

PI = FIB.DESCR ;Address of information block 


;descriptor 

BLBC RO,10$ ;If low bit = 0, access 

;failure 

MOVZWL IO.STATUS,RO ;Get final I/O completion 

;status 


Example 3-1 Cont'd. on next page 
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Example 3-1 (Cont.) Disk Program Example 


BLBS 


RO,30$ 


10$: PUSHL RO 

$DASSGN_S CHAN = DEVICE_CHANNEL 
POPL RO 
20$: RET 


;If low bit set, successful 
;I/0 function 
;Save error status 
;Deassign file device channel 
;Retrieve error status 
;Return with I/O error status 


The file is now ready to be read and written randomly. Since the 
records are fixed length and exactly one block long, the record 
number corresponds to the virtual block number of the record in the 
file. Thus a particular record can be read or written simply by 
specifying its record number in the file. 

The following code reads two records at a time and checks to see 
that they contain their respective record numbers in every byte. 

The records are then written back into the file in reverse order. 
This results in record 1 having the old contents of record 2 and 
record 2 having the old contents of record 1, and so forth. After 


; utility be used to verify the change : 

in data positioning. 

30$ MOVZBL 

#1 ,R6 

;Set starting record (block) 



;number 

; Read next two 

records into block buffer. 

40$: $QI0_S 

CHAN = DEVICE.CHANNEL,- 

;Read next two records from 


- 

;file channel 


FUNC = #IO$_READVBLK.- 

;I/0 function is read virtual 


- 

;block 


IOSB = IO.STATUS,- 

;Address of I/O status 


- 

;quadword 


PI = BLOCK.BUFFER,- 

;Address of I/O buffer 


P2 = #1024.- 

;Size of I/O buffer 


P3 = R6 

;Starting virtual block of 
;transfer 

BSBB 

50$ 

;Check I/O completion status 

; Check each record to make sure it contains the correct data. 

SKPC 

R6,#512.BL0CK_BUFFER 

;Skip over equal record 
;numbers in data 

BNEQ 

60$ 

;If not equal, data match 
;failure 

ADDL3 

#1,R6,R5 

;Calculate even record number 

SKPC 

R5.#512.BL0CK_BUFFER+512 

;Skip over equal record 
;numbers in data 

BNEQ 

60$ 

;If not equal, data match 
;failure 

; Record data matches. 


; Write records 

in reverse order in file 


Example 3—1 Cont'd. on next page 
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Example 3-1 (Cont.) Disk Program Example 


$QI0W_S CHAN = DEVICE_CHANNEL.- 

FUNC = #IO$_WRITEVBLK,- 

IOSB = ICLSTATUS,- 

P1 = BL0CK_BUFFER+512,- 
P2 = #512,- 
P3 = R6 
BSBB 50$ 

ADDL3 #1,R6,R5 

$QI0W_S CHAN = DEVICE.CHANNEL,- 

FUNC = #IO$_WRITEVBLK,- 

IOSB = IO.STATUS,- 

P1 = BLOCK_BUFFER,- 
P2 = #512,- 
P3 = R5 
BSBB 50$ 

ACBB #NUM_RECS-1,#2,R6,40$ 

BRB 70$ 


Write even-numbered record in 
odd slot 

I/O function is write virtual 
block 

Address of I/O status 
quadword 

Address of even record buffer 
Length of even record buffer 
Record number of odd record 
Check I/O completion status 
Calculate even record number 
Write odd numbered record in 
even slot 

I/O function is write virtual 
block 

Address of I/O status 
quadword 

Address of odd record buffer 
Length of odd record buffer 
Record number of even record 
Check I/O completion status 
Any more records to be read? 


; Check I/O completion status. 

50$: BLBC R0,70$ 

MOVZWL IO.STATUS,RO 

BLBC R0,70$ 

RSB 

; Record number mismatch in data. 
60$: MNEGL #4,R0 


If low bit = 0, service 
failure 

Get final I/O completion 
status 

If low bit = 0, I/O function 
failure 


;Set dummy error status value 


All records have been read, verified, and odd/even pairs inverted 


70$: 


PUSHL RO 

$QI0W_S CHAN = DEVICE.CHANNEL,- 
FUNC = #IO$_DEACCESS 
$DASSGN_S CHAN = DEVICE_CHANNEL 
POPL RO 
RET 


;Save final status 
;Deaccess file 

;I/O function is deaccess file 
;Deassign file device channel 
;Retrieve final status 


.END DISK.EXAMPLE 
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Laboratory Peripheral Accelerator Driver 


This chapter describes the VMS laboratory peripheral accelerator (LPA11-K) 
driver and the high-level language procedure library that interfaces with 
it. The procedure library is implemented with callable assembly language 
routines that translate arguments into the format required by the LPA11-K 
driver and that handle buffer chaining operations. Routines for loading the 
microcode and initializing the device are also described. 

Refer to the LPAU-K Laboratory Peripheral Accelerator User's Guide for 
additional information. 


4.1 Supported Device 

The LPA11-K is a peripheral device that controls analog-to-digital (A/D) and 
digital-to-analog (D/A) converters, digital I/O registers, and real-time clocks. 
It is connected to the VAX processor through the UNIBUS adapter. 

The LPA11-K is a fast, flexible microprocessor subsystem designed for 
applications requiring high-speed, concurrent data acquisition and data 
reduction. The LPA11-K allows aggregate analog input and output rates of 
up to 150,000 samples per second. The maximum aggregate digital input and 
output rate is 15,000 samples per second. 

Table 4-1 lists the useful minimum and maximum LPA11-K configurations 
supported by the VMS operating system. 


4.1.1 LPA11 -K Modes of Operation 

The LPA11-K operates in two modes: dedicated and multirequest. 

In dedicated mode, only one user (one request), can be active at a time, and 
only analog I/O data transfers are supported. Up to two A/D converters can 
be controlled simultaneously. One D/A converter can be controlled at a time. 
Sampling is initiated either by an overflow of the real-time clock or by an 
externally supplied signal. Dedicated mode provides sampling rates of up to 
150,000 samples per second. 


Table 4—1 Minimum and Maximum Configurations per LPA11 -K 

Minimum 

Maximum 

1 DD11-Cx or Dx backplane 

1 KW11 -K real-time clock 

1 of the following: 

ADI 1-K A/D converter 

AA11-K A/D converter 

DR 11-K digital I/O register 

2 DD11-Cx or Dx backplanes 

1 KW11-K real-time clock 

2 ADI 1-K A/D converters 

2 AMI 1-K multiplexers for ADI 1-K converters 

1 AA11-K D/A converter 

5 DR 11-K digital I/O registers 
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4.1 Supported Device 


In multirequest mode, sampling from all of the devices listed in Table 4-1 
is supported. The LPA11-K operates like a multicontroller device; up to 
eight requests (from one through eight users) can be active simultaneously. 
The sampling rate for each user is a multiple of the common real-time clock 
rate. Independent rates can be maintained for each user. Both the sampling 
rate and the device type are specified as part of each data transfer request. 
Multirequest mode provides a maximum aggregate sampling rate of 15,000 
samples per second. 


4.1.2 Errors 

The LPA11-K returns the following classes of errors: 

1 Errors associated with the issuance of a new LPA11-K command 
(SS$_DEVCMDERR) 

2 Errors associated with an active data transfer request (SS$_DEVREQERR) 

3 Fatal hardware errors that affect all LPA11-K activity (SS$_CTRLERR) 

Appendix A of the LPA11-K Laboratory Peripheral Accelerator User's Guide lists 
these three classes of errors and the specific error codes for each class. The 
LPA11-K aborts all active requests if any of the following conditions occur: 

• Power failure 

• Device timeout 

• Fatal error 

Power failure is reported to any active users when power is recovered. 

The LADRIVER times out all $QIOs after two seconds if they have not 
completed. The driver does not provide any parameters that allow the user to 
change the length of the timeout. 

The timeout period applied to all $QIOs can be changed with the following 
PATCH commands executed from a privileged account: 

$ PATCH SYSSSYSTEM: LADRIVER. EXE/OUTPUT=SYS$SYSTEM: LADRIVER EXE 
PATCH>SET ECO 25 

PATCH>REPLACE/INSTRUCTION LA$TIMEOUT_VALUE 

0LD>'PUSHL I* #00000002 1 

0LD>EXIT 

NEW>’PUSHL I* #0000003C' 

NEW>EXIT 

PATCH>UPDATE 

PATCH>EXIT 

Substitute the desired timeout value for the "0000003C" in the example above. 
When you reboot, the system loads the new copy of the driver containing the 
new timeout value. 

Device timeouts are monitored only when a new command is issued. For 
data transfers, the time between buffer full interrupts is not defined. Thus, no 
timeout errors are reported on a buffer-to-buffer basis. 

If a required resource is not available to a process, an error message is 
returned immediately. The driver does not place the process in the resource 
wait mode. 
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4.2 Supporting Software 

The LPA11-K is supported by a device driver, a high-level language 
procedure library of support routines, and routines for loading the microcode 
and initializing the device. The system software and support routines provide 
a control path for synchronizing the use of buffers, specifying requests, and 
starting and stopping requests; the actual data algorithms for the laboratory 
data acquisition I/O devices are accomplished by the LPA11-K. 

The LPA11-K driver and the associated I/O interface have the following 
features: 

• They permit multiple LPA11-K subsystems on a single UNIBUS adapter. 

• They operate as an integral part of the VMS operating system. 

• They can be loaded on a running VMS operating system without relinking 
the executive. 

• They handle I/O requests, function dispatching, UNIBUS adapter 
map allocation, interrupts, and error reporting for multiple LPA11-K 
subsystems. 

• The LPA11-K functions as a multibuffered device. Up to eight buffer 
areas can be defined per request. Up to eight requests can be handled 
simultaneously. Buffer areas can be reused after the data they contain is 
processed. 

• Because the LPA11-K chains buffer areas automatically, a start data 
transfer request can transfer an infinite and noninterrupted amount of 
data. 

• Multiple ASTs are dynamically queued by the driver to indicate whena 
buffer has been filled (the data is available for processing) or emptied (the 
buffer is available for new data). 

The high-level language support routines have the following features: 

• They translate arguments provided in the high-level language calls into 
the format required for the Queue I/O interface. 

• They provide a buffer chaining capability for a multibuffering 
environment by maintaining queues of used, in use, and available buffers. 

• They adhere to all VMS conventions for calling sequences, use of 
shareable resources, and reentrancy. 

• They can be part of a resident global library, or they can be linked into a 
process image as needed. 

The routines for loading microcode and initializing devices have the following 
features: 

• They execute, as separate processes, images that issue I/O requests. 
These I/O requests initiate microcode image loading, start the LPA11-K 
subsystem, and automatically configure the peripheral devices on the 
LPA11-K internal I/O bus. 
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4.2 Supporting Software 


The y ke executed at the request of the user or an operator. 

• They can be executed at the request of other processes. 

• They can be executed automatically when the system is initialized and on 
power recovery. 

Figure 4-1 shows the relationship of the supporting software to the LPA11-K. 

Figure 4-1 Relationship of Supporting Software to LPA11 -K 



ZK-658-82 


4.3 


Device Information 


You can obtain information on all peripheral data acquisition devices on the 
LPA11-K internal I/O bus by using the Get Volume Information ($GETDVI) 
system service. (See the VMS System Services Reference Manual.) 

SGETDVI returns device characteristics when you specify the item 
codes DVI$_DEVCHAR and DVI$_DEVDEPEND. Tables 4-2 and 
4-3 list these characteristics. The $DEVDEF macro defines the device¬ 
independent characteristics; the $LADEF macro defines the device-dependent 
characteristics. Device-dependent characteristics are set by the set clock, 
initialize, and load microcode I/O functions to any one of, or a combination 
of, the values listed in Table 4-3. 


DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device 
type names, which are defined by the $DCDEF macro. The device class for 
the LPA11-K is DC$_REALTIME; the device type is DT$_LPA11. 
DVI$_DEVBUFSIZ is not applicable to the LPA11-K. 
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4.3 Device Information 

Table 4—2 LPA11 -K Device-Independent Characteristics 


Characteristic 1 

Meaning 

Dynamic Bit (Conditionally Set) 

DEV$M_AVL 

Device is online and available. 

Static Bits (Always Set) 

DEV$M_IDV 

DEV$M_ODV 

DEV$M_RTM 

DEV$M SHR 

Device is capable of input. 

Device is capable of output. 

Device is real-time. 

Device is shareable. 


’Defined by the $DEVDEF macro. 


Table 4-3 LPA11 -K Device-Dependent Characteristics 


Field 1 

Meaning 

LA$M_MCVALID 
LA$V_MC VALID 

The load microcode I/O function (IO$_LOADMCODE) was 
performed successfully. LA$M_MCVALID is set by 
IO$_LOADMCODE. Each microword is verified by reading it 
back and comparing it with the specified value. 

LASM_MCVALID is cleared if there is no match. 

LA$V_MCTYPE 

LA$S_MCTYPE 

The microcode type, set by the load microcode I/O function 

(IO$_LOADMCODE), is one of the following values: 

Value Meaning 

LA$K_MRMCODE Microcode type is in multirequest 

mode. 

LA$K_ADMCODE Microcode type is in dedicated A/D 

mode. 

LA$K_DAMCODE Microcode type is in dedicated D/A 

mode. 


Defined by the $LADEF macro. 
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4.3 Device Information 


Table 4-3 (Cont.) LPA11 -K Device-Dependen t Characteristics 

Field 1 Meaning 


LA$V CONFIG 

LA$S_CONFIG 


The bit positions, set by the initialize I/O function 

(10$—INITIALIZE), for the peripheral data acquisition devices 
on the LPA11-K internal I/O bus are one or more of the 
following: 


Value 

Meaning 

LA$V_CLOCKA 

LA$M_CLOCKA 

Clock A 

LA$V_CLOCKB 

LA$M_CLOCKB 

Clock B 

LA$ V_AD 1 
LA$M_AD1 

A/D device 1 

LA$V_AD2 

LA$M_AD2 

A/D device 2 

LA$V_DA 

LA$M_DA 

D/A device 1 

LAS V_DI01 
LA$M_DI01 

Digital I/O buffer 1 

LA$V_DI02 

LA$M_DI02 

Digital I/O buffer 2 

LA$V_DI03 

LA$M_DI03 

Digital I/O buffer 3 

LA$V_DI04 

LA$M_DI04 

Digital I/O buffer 4 

LA$V_DI05 

LA$M DI05 

Digital I/O buffer 5 


LA$V_RATE 

LA$S_RATE 


The Clock A rate, which is set by the set clock function 
(IO$_SETCLOCK), is one of the following values: 

Value Meaning 


0 Stopped 

1 1 MHz 

2 100 kHz 

3 10 kHz 

4 1 kHz 

5 100 Hz 

6 Schmidt trigger 

7 Line frequency 


’Defined by the $LADEF macro. 
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4.3 Device Information 


Table 4-3 (Cont.) LPA11 -K Device -Dependent Characteristics 

Field 1 Meaning_ 

LA$V_PRESET The Clock A preset value set by the set clock 

LA$S_PRESET 

1 Defined by the $LADEF macro. 


4.4 LPA11 -K Function Codes 

The LPA11-K I/O functions are as follows: 

• Load the microcode into the LPA11-K. 

• Start the LPA11-K microprocessor. 

• Initialize the LPA11-K subsystem. 

• Set the LPA11-K real-time clock rate. 

• Start a data transfer request. 

The first three functions are normally performed by the loader process, not by 
the user's data transfer program. See Section 4.5.21 for a description of the 
loader process interface. 

The Cancel I/O on Channel ($CANCEL) system service is used to abort data 
transfers. 


4.4.1 Load Microcode 

This I/O function resets the LPA11-K and loads an image of LPA11-K 
microcode. Physical I/O privilege is required. The following function code is 

provided: 

• IO$_LOADMCODE—Load microcode 


The load microcode function takes the following device- or function- 
dependent arguments: 

• pi—The starting virtual address of the microcode image that is to be 
loaded into the LPA11-K 

• P2—The number of bytes (usually 2048) that are to be loaded 

• p3—The starting microprogram address (usually 0) in the LPA11-K that 
is to receive the microcode 


If anv data transfer requests are active at the time a load microcode request i 
issued, the load request is rejected and SS$_DEVACTIVE is returned in the 
I/O status block. 


Each microword is verified by comparing it with the specified value in 
memory. If all words match (the microcode was loaded successfully) 
the driver sets the microcode valid bit (LA$Y_MCVALID) in the device¬ 
dependent characteristics longword (see Table 4-3). If there is no match. 
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4.4 LPA11-K Function Codes 


SS$ DATACHECK is returned in the I/O status block and LA$V__MCVALID 
is cleared to indicate that the microcode was not properly loaded. If the 
microcode was loaded successfully, the driver stores one of the microcode 
type values (LA$K_MRCODE, LA$K__ADCODE, or LA$K__DAMCODE) in 
the characteristics longword. 

After a load microcode function is completed, the second word of the I/O 
status block contains the number of bytes loaded. 


4.4.2 Start Microprocessor 

This I/O function resets the LPA11-K and starts (or restarts) the LPA11-K 
microprocessor. Physical I/O privilege is required. The following function 
code is provided: ° 

• IO$_STARTMPROC—Start microprocessor 

This function code takes no device- or function-dependent arguments. 

The start microprocessor function can return five error codes in the I/O status 
block (see Section 4.6): ' 

SS$_CTRLERR SS$_DEVACTIVE SS$_MCNOTVALID 

SS$_POWERFAIL SS$_TIMEOUT 

Appendix A of the the LPA11-K Laboratory Peripheral Accelerator User's Guide 
provides additional information on error codes. 


4.4.3 Initialize LPA11-K 

This I/O function issues a subsystem initialize command to the LPA11-K 
This command specifies LPA11-K laboratory I/O device addresses and other 
table information for the subsystem. It is issued only once after restarting 
the subsystem and before any other LPA11-K command is given. Physical 
I/O privilege is required. The VMS operating system defines the following 
function code: & 

• IO$_INITIALIZE—Initialize LPA11 -K 

The initialize LPA11-K function takes the following device- or function- 
dependent arguments: 

Pl-Thestarting, word-aligned, virtual address of the initialize command 
table in the user process. This table is read once by the LPA11-K during 
the execution of the initialize command. See the LPAU-K Laboratory 
Peripheral Accelerator User's Guide for additional information. 

* P2 —Length of the initialize command buffer (always 278 bytes). 

If the initialize function is completed successfully, the appropriate device 
(seeTaWe^-S^ 311165 ^ ^ ^ device ' de P endent characteristics longword 
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The initialize function can return the following 10 error codes in the I/O 
status block: 


SS$_BUFNOT ALIGN 
SS$_DEVCMDERR 
SS$_IVMODE 
SS$_TIMEOUT 


SS$_CANCEL 
SS$_INCLENGTH 
SS$_MCNOT V ALID 


SS$_CTRLERR 

SS$_INSFMAPREG 

SS$_POWERFAIL 


If a device specified in the initialize command table is not in the LPA11-K 
configuration, an error condition (SS$_DEVCMDERR) occurs and the address 
of the first device not found is returned in the LPA11-K maintenance status 
register (see Section 4.6). A program can use this characteristic to poll the 
LPA11-K and determine the current device configuration. 


Set Clock 

This virtual function issues a clock control command to the LPA11-K. The 
clock control command specifies information necessary to start, stop, or 
change the sample rate at which the real-time clock runs on the LPA11-K 
subsystem. 

Note: If the LPA11-K has more than one user, caution should be exercised when 
the clock rate is changed. In multirequest mode, a change in the clock 
rate affects all users. 

The following function code is provided: 

• IO$_SETCLOCK—Set clock 

The set clock function takes the following device- or function-dependent 
arguments: 

• P2—Mode of operation. The VMS operating system defines the following 
clock start mode word (hexadecimal) values: 


Value Meaning 


1 

KW11-K Clock A 

11 

KW11-K Clock B 

P3—Clock control and status. The VMS operating system defines the 
following clock status word (hexadecimal) values: 

Value 

Meaning 

0 

Stop clock 

143 

1 MHz clock rate 

145 

100 kHz clock rate 

147 

10 kHz clock rate 

149 

1 kHz clock rate 

14B 

100 Hz clock rate 

14D 

Clock rate is Schmidt trigger 1 

14F 

Clock rate is line frequency 
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4.4 LPA11-K Function Codes 


• P4 The two's complement of the real-time clock preset value. The range 
is 16 bits for the KW11-K Clock A and 8 bits for the KW11-K Clock B. 

The LPA11-K Laboratory Peripheral Accelerator User's Guide describes the clock 
start mode word and the clock status word in greater detail. 

If the set clock function is completed successfully for Clock A, the clock rate 
and preset values are stored in the device-dependent characteristics longword 
(see Table 4-3). & 

The set clock function can return six error codes in the I/O status block (see 
Section 4.6): v 

SS$_CANCEL SS$_CTRLERR SS$_DEVCMDERR 

SS$_MCNOTVALID SS$_POWERFAIL SS$_TIMEOUT 

Appendix A of the the LPAU-K Laboratory Peripheral Accelerator User's Guide 
provides additional information on error codes. 


4.4.5 Start Data Transfer Request 

This virtual I/O function issues a data transfer start command that specifies 
i rf,\ a< ^ r ? sses ' sample mode, and sample parameters used by the 
LPA11-K. This information is passed to the data transfer command table The 
following function code is provided: 

• IO$_STARTDATA—Start data transfer request 

The start data transfer request function takes the following function modifier: 

• IO$M_SETEVF—Set event flag 

The start data transfer request function takes the following device- or 
function-dependent arguments: 

• PI—The starting virtual address of the data transfer command table in 
the user's process. 

• P2 The length in bytes (always 40) of the data transfer command table. 

• P3—The AST address of the normal buffer completion AST routine 
(optional). 

• The AST address of the buffer overrun completion AST routine 
(optional). This argument is used only when the buffer overrun bit 

(LA$M_BFROVRN) is set, that is, when a buffer overrun condition is 
classified as a nonfatal error. 

A buffer overrun condition differs from a data overrun condition. The 
LPA11-K fetches data from, or stores data in, memory. If data cannot be 
fetched quickly enough (for example, when there is too much UNIBUS 
activity) a data underrun condition occurs. If data cannot be stored quickly 
enough, a data overrun condition occurs. After each buffer is filled or 
emptied, the LPA11-K obtains the index number of the next buffer to process 
from the user status word (USW). (See Section 2.5 of the LPAU-K Laboratory 
Peripheral Accelerator User's Guide.) A buffer overrun condition occurs if 
the LPA11-K fills or empties buffers faster than the application program 
can supply new buffers. For example, buffer overrun can occur when the 
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sampling rate is too high, the buffers are too small, or the system load is too 
heavy. 

The LPA11-K driver accesses the 10-longword data transfer command table, 
shown in Figure 4-2, when the data transfer start command is processed. 
After the command is accepted and data transfers begin, the driver does not 
access the table. 

Figure 4-2 Data Transfer Command Table 


31 24 23 16 15_8_7 
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buffer and buffer 
overrun bit 

mode 
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trigger 
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ZK-660-82 


In the first longword of the data transfer command table, the first two bytes 
contain the LPA11-K start data transfer request mode word. (Section 3.4.1 
of the LPA11-K Laboratory Peripheral Accelerator User’s Guide describes the 
functions of this word.) 

The third byte contains the number (0-7) of the highest buffer available and 
the buffer overrun flag bit (bit 23; values: LA$M_BFROVRN and 
LA$V_BFROVRN). If this bit is set, a buffer overrun condition is a nonfatal 
error. 

The second longword contains the user status word address (see Section 3.4.3 
of the LPA11-K Laboratory Peripheral Accelerator User's Guide). This virtual 
address points to a two-byte area in the user-process space and must be word 
aligned. 
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The third longword contains the size (in bytes) of the overall buffer area. The 
virtual address in the fourth longword is the beginning address of this area. 
This address must be longword aligned. The overall buffer area contains 
a specified number of buffers (the number of the highest available buffer 
specified in the first longword plus one). Individual buffers are subject to 
length restrictions: in multirequest mode the length must be in multiples of 
two bytes; in dedicated mode the length must be in multiples of four bytes. 
All data buffers are virtually contiguous for each data transfer request. 

The fifth and sixth longwords contain the random channel list (RCL) length 
and address, respectively. The RCL address must be word aligned. The last 
word in the RCL must have bit 15 set. (See Section 3.4.6 of the LPAU-K 
Laboratory Peripheral Accelerator User's Guide for additional information on 
the RCL.) 

The seventh through tenth longwords contain LPAll-K-specific sample 
parameters. The driver passes these parameters directly to the LPA11-K. 

(See the LPAU-K Laboratory Peripheral Accelerator User's Guide for a detailed 
description of their functions.) 


The start data transfer request function can return the following 15 error 
codes in the I/O status block (see Section 4.6): 


SS$_ABORT 
SS$_CTRLERR 
SS$_EXQUOT A 
SS$_INSFMAPREG 
SS$_PARITV 


SS$_BUFNOT ALIGN 

SS$_DEVCMDERR 

SS$_INCLENGTH 

SS$_INSFMEM 

SS$_POWERFAIL 


SS$_CANCEL 

SS$_DEVREQERR 

SS$_INSFBUFDP 

SS$_MCNOTVALID 

SS$_TIMEOUT 


Data buffers are chained and reused as the LPAU-K and the user process 
dispose of the data. As each buffer is filled or emptied, the LPA11-K driver 
notifies the application process either by setting the event flag specified by 
the QIO request efn argument or by queuing an AST. Since buffer use is a 
continuing process, the event flag is set or the AST is queued a number of 
times. The user process must clear the event flag (or receive the AST), process 
the data, and specify the next buffer for the LPA11-K to use. 

If the set event flag function modifier (IO$M_SETEVF) is specified, the event 
flag is set repeatedly: when the data transfer request is started, after each 
buffer completion, and when the request completes. If IO$M_SETEVF is not 
specified, the event flag is set only when the request completes. 

ASTs are preferred over event flags for synchronizing a program with the 
LPA11-K, because AST delivery is a queued process, while the setting of 
event flags is not. If only event flags are used, it is possible to lose buffer 
status. 


Three AST addresses can be specified. For normal data buffer transactions 
the AST address specified in the P3 argument is used. If the buffer overrun 
bit in the data transfer command table is set and an overrun condition occurs 
the AST address specified in the P4 argument is used. The AST address 
specified in the astadr argument of the QIO request is used when the entire 
data transfer request is completed. The astprm argument specified in the QIO 
request is passed to all three AST routines. 
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If insufficient dynamic memory is available to allocate an AST block, an error 
(SS$_INSFMEM) is returned. If the user does not have sufficient AST quota 
remaining to allocate an AST block, an error (SS$_EXQUOTA) is returned In 
either case, the request is stopped. Normally, there are never more than three 
outstanding ASTs per LPA11-K request. 


4.4.6 LPA11 -K Data Transfer Stop Command 

The Cancel I/O on Channel ($CANCEL) system service is used to abort 
data transfers for a particular process. When the LPA11-K driver receives a 
$CANCEL request, a data transfer stop command is issued to the LPA11-K. 

To stop a data transfer, set bit 14 of the user status word. If this bit is set, the 
transfer stops at the end of the next buffer transaction (see Section 2.5 of the 
LPA11-K Laboratory Peripheral Accelerator User's Guide). 


4.5 High-Level Language Interface 

The VMS operating system supports several program-callable procedures that 
provide access to the LPA11-K. The formats of these calls are documented 
in this manual for VAX FORTRAN users. VAX MACRO users must set up 
a standard VMS argument block and issue the standard CALL procedure. 
(VAX MACRO users can also access the LPA11-K directly through the use 
of the device-specific QIO functions described in Section 4.4.) Users of 
other high-level languages must specify the proper subroutine or procedure 
invocation. 


4.5.1 High-Level Language Support Routines 

The VMS operating system provides 20 high-level language procedures for 
the LPA11-K. These procedures are divided into four classes. Table 4-4 lists 
the classes and the VAX procedures for the LPA11-K. 


Table 4-4 VAX Procedures for the LPA11 -K 

Class 

Subroutine 

Function 

Sweep Control 

LPASADSWP 

Start A/D converter sweep 


LPASDASWP 

Start D/A converter sweep 


LPASDISWP 

Start digital input sweep 


LPA$DOSWP 

Start digital output sweep 


LPASLAMSKS 

Specify LPA11-K controller and digital mask 
words 


LP ASSET ADC 

Specify channel select parameters 


LPASSETIBF 

Specify buffer parameters 


LPASSTPSWP 

Stop sweep 

Clock control 

LPASCLOCKA 

Set Clock A rate 


LPASCLOCKB 

Set Clock B rate 


LPASXRATE 

Compute clock rate and preset value 
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Table 4-4 (Cont.) VAX Procedures for the LPA11 -K 


Class 

Subroutine 

Function 

Data Buffer 

LPA$IBFSTS 

Return buffer status 

Control 

LPA$IGTBUF 

Return next available buffer 


LPA$INXTBF 

Alter buffer order 


LPA$IWTBUF 

Return next buffer or wait 


LPA$RLSBUF 

Release buffer to LPA11-K 


LPA$RMVBUF 

Remove buffer from device queue 

Miscellaneous 

LPASCVADF 

Convert A/D input to floating point 


LPA$FLT16 

Convert unsigned integer to floating point 


LPA$LOADMC 

Load microcode and initialize LPA11-K 


4.5.1.1 Buffer Queue Control 

This section is provided for informational purposes only. 

Buffer queue control for data transfers by LPA11-K subroutines involves the 
use of the following queues: 

• Device queue (DVQ) 

• User queue (USQ) 

• In-use queue (IUQ) 

Each data transfer request can specify from one through eight data buffer 
areas. The user specifies these buffers by address. During execution of the 
request, the LPA11-K assigns an index from 0 through 7 when a buffer is 
referenced. 

The DVQ contains the indexes of all the buffers that the user has released 
(buffers made available to be filled or emptied by the LPA11-K). For output 
functions (D/A and digital output), these buffers contain data to be output by 
the LPA11-K. For input functions (A/D and digital input), these buffers are 
empty and waiting to be filled by the LPA11-K. 

The USQ contains the indexes of all buffers that are waiting to be returned 
to the user. The LPA$IWTBUF and LPA$IGTBUF calls are used to return the 
index of the next buffer in the USQ. For output functions (D/A and digital 
output), these buffers are empty and waiting to be filled by the application 
program. For input functions (A/D and digital input), these buffers contain 
data to be processed by the application program. 

The IUQ contains the indexes of all buffers that are currently being processed 
by the LPA11-K. Normally, the IUQ contains the indexes of the following 
buffers: 6 

• The buffer currently being filled or emptied by the LPA11-K 

• The next buffer to be filled or emptied by the LPA11-K. (This is the buffer 
specified by the next buffer index field in the user status word.) 

Because the LPA11-K driver requires that at least one buffer be ready when 
the input or output sweep is started, the user must call the LPA$RLSBUF 
subroutine before the sweep is initiated. 

Figure 4—3 shows the flow between the buffer queues. 
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4.5.1.2 Subroutine Argument Usage 

Table 4-5 describes the general use of the subroutine arguments. The 
subroutine descriptions in the following sections contain additional 
information on argument usage. The (IBUF), (BUF), and (ICHN) (random 
channel list address) arguments must be aligned on specific boundaries. 

Figure 4—3 Buffer Queue Control 



LPA$RLSBUF 
(FROM APPLICATION 
PROGRAM) 


Table 4-5 

Subroutine Argument Usage 

Argument 

Meaning 

IBUF 

A 50-longword array initialized by the LPASSETIBF subroutine. 
IBUF is the impure area used by the buffer management 
subroutines. A unique IBUF array is required for each 
simultaneously active request. IBUF must be longword aligned. 

The first quadword in the IBUF array is an I/O status block 
(IOSB) for high-level language subroutines. The LPA$IGTBUF and 
LPA$IWTBUF subroutines fill this quadword with the current and 
completion status (see Section 4.6). 

LBUF 

Specifies the size of each data buffer in words (must be even 
for dedicated mode sweeps). All buffers are the same size. 

The minimum value for LBUF is 6 for multirequest mode data 
transfers and 258 for dedicated mode data transfers. The 
aggregate size of the assigned buffers must be less than 32,768 
words. Thus, the maximum size of each buffer (in words) is 
limited to 32,768 divided by the number of buffers. The LBUF 
argument length is one word. 
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Table 4-5 (Cont.) Subroutine Argument Usage 

Argument Meaning 


NBUF 


MODE 


IRATE 


Specifies the number of times the buffers are to be filled during 

the life of the request. If 0 (default) is specified, sampling 
is indefinite and must be stopped with the LPASSTPSWP 
subroutine. The NBUF argument length is one longword. 

Specifies sampling options. MODE bit values are listed in the 
appropriate subroutine descriptions. The default is 0. MODE 
values can be added to specify several options. No options are 
mutually exclusive, although not all bits can be applicable at the 
same time. The MODE argument length is one word. 

Specifies the clock rate as follows: 


Value 

Meaning 

-1 

Direct-coupled Schmidt trigger 1 (Clock A only) 

0 

Clock B overflow or no rate 

1 

1 MHz 

2 

100 kHz 

3 

10 kHz 

4 

1 kHz 

5 

100 Hz 

6 

Schmidt trigger 

7 

Line frequency 


IPRSET 


DWELL 


The IRATE argument length is one longword. 

Specifies the hardware clock preset value. This value is 
the two's complement of the desired number of clock ticks 
between clock interrupts. (The maximum value is 0, the two’s 
complement of 65,536.) IPRSET can be computed by the 
LPA$XRATE subroutine. The IPRSET argument length is one 
word. 

Specifies the number of hardware clock overflows between 
sample sequences in multirequest mode. For example, if DWELL 
is 20 and NCHN is 3, then after 20 clock overflows one channel 
is sampled on each of the next three successive overflows; 
no sampling occurs for the next 20 clock overflows. This 
allows different users to use different sample rates with the 
same hardware clock overflow rate. In dedicated mode, the 
hardware clock overflow rate controls sampling and DWELL is 
not accessed. Default for DWELL is 1. The DWELL argument 
length is one word. 
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Table 4-5 (Cont.) Subroutine Argument Usage_ 

Argument M eaning ___ 

IEFN Specifies the event flag number or completion routine address. 

The selected event flag is set at the end of each buffer 
transaction. If IEFN is 0 (default), event flag 22 is used. 

IEFN can also specify the address of a completion routine. 

This routine is called by the buffer management routine when 
a buffer is available and when the request is terminated, either 
successfully or with an error. The standard VMS calling and 
return sequences are used. The completion routine is called from 
an AST routine and is therefore at AST level. 

If IEFN specifies the address of a completion routine, the 
program must call the LPA$IGTBUF subroutine to obtain the 
next buffer. If IEFN specifies an event flag, the program must call 
the LPASIWTBUF subroutine to obtain the next buffer and must 
use the %VAL operator: 

,7.VAL(3), (Event flag 3) 

,BFRFULL, (Address of completion 

routine) 

The IEFN argument length is one longword. 

If multiple sweeps are initiated, they must use different event 
flags. The software does not enforce this policy. 

Event flag 23 is reserved for use by the LPA$CLOCKA and 
LPASCLOCKB subroutines. If either of these subroutines is 
included in the user program, event flag 23 cannot be used. 
Also, if IEFN is defaulted, event flag 22 cannot be used in the 
user program. 

LDELAY Specifies the delay, in IRATE units, from the start event until the 

first sample is taken. The maximum value is 65,535; default is 
1. The LDELAY argument length is one word. The LPA11-K 
supports the LDELAY argument in multirequest mode only. 

ICHN Specifies the number of the first I/O channel to be sampled. 

Default is channel 0. The ICHN argument length is one byte. The 
channel number is not the same as the channel assigned to the 
device by the $ ASSIGN system service. The LPA11-K uses the 
channel number to specify the multiplexer address of an A/D, 
D/A, or digital I/O device on the LPA11-K internal I/O bus. 

NCHN Specifies the number of I/O device channels to sample in a 

sample sequence. Default is 1. If the NCHN argument is 1, 
the single channel bit is set in the mode word of the start 
request descriptor array (RDA) when the sweep is started. The 
RDA contains the information needed by the LPA11-K for each 
command (see the LPA11-K Laboratory Peripheral Accelerator 
User's Guide). The NCHN argument length is one word. 

IND Receives the VMS success or failure code of the call. The IND 

argument length is one longword. 
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4.5.2 LPA$ADSWP — Initiate Synchronous A/D Sampling Sweep 

The LPA$ADSWP subroutine initiates A/D sampling through an AD11-K. 

The format of the LPA$ADSWP subroutine call is as follows: 

CALL LPA$ADSWP (IBUF,LBUF,[NBUF],[MODE],[DWELL],[IEFN],- 
[LDELAY],[ICHN],[NCHN],[IND]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

MODE Specifies sampling options. The VMS operating system defines the 
following sampling option values: 

Value Meaning 


32 

64 

512 


1024 

2048 

4096 

8192 

16384 


Parallel A/D conversion sample algorithm is used if dual A/D 
converters are specified (value = 8192). Absence of this bit 
implies the serial A/D conversion sample algorithm. 

Multirequest mode request. Absence of this bit implies a 
dedicated mode request. 

External trigger (Schmidt trigger 1). Dedicated mode only. 
This value is used when a user-supplied external sweep 
trigger is desired. The external trigger is supplied by the 
KW11-K (Schmidt trigger 1 output) to the ADI 1-K (external 
start input). If MODE=512, the user process must specify 
a Clock A rate of -1 for proper A/D sampling. This is 
nonclock-driven sampling (see Section 4.5.10). (The 
LPA 11-K Laboratory Peripheral Accelerator User's Guide 
provides additional information on the use of external 
triggers.) 

Time stamped sampling with Clock B. The double word 
consists of one data word followed by the value of the 
LPA11-K's internal 16-bit counter at the time of the sample 
(see Section 2.4.3 in the LPA 11-K Laboratory Peripheral 
Accelerator User's Guide). Multirequest mode only. 

Event marking. Multirequest mode only. (The LPA 11-K 
Laboratory Peripheral Accelerator User's Guide describes 
event marking.) 

Start method. If selected, the digital input start method is 
used. If not selected, the immediate start method is used. 
Multirequest mode only. 

Dual A/D converters are to be used. Dedicated mode only. 

Buffer overrun is a nonfatal error. The LPA 11-K will 
automatically default to fill buffer 0 if a buffer overrun 
condition occurs. 


If MODE is defaulted, A/D sampling starts immediately with absolute 
channel addressing in dedicated mode. The LPA 11-K does not 
support delays in dedicated mode. 
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IND Returns the success or failure status as follows: 

0 = Error in call. Possible causes are the following: LPA$SETIBF 
subroutine was not previously called; LPA$RLSBUF subroutine was not 
previously called; size of data buffers disagrees with the size computed 
by the LPA$SETIBF subroutine call. 

1 = successful sweep started 
nnn = VMS status code 


4.5.3 LPA$DASWP — Initiate Synchronous D/A Sweep 

The LPASDASWP subroutine initiates D/A output to an AA11-K. 


The format for the LPA$DASWP subroutine call is as follows: 

CALL LPASDASWP (IBUF,LBUF,[NBUF],[MODE],[DWELL],[IEFN],- 
[LDELAY],[ICHN],[NCHN],[IND]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

MODE Specifies the sampling options. The VMS operating system defines 

the following start criteria values: 

Value 

Meaning 

0 

Immediate start. This is the default value for MODE. 

64 

Multirequest mode. If not selected, this request is for 
dedicated mode. 

4096 

Start method. If selected, the digital input start method is 
used. If not selected, the immediate start method is used. 
Multirequest mode only. 

16384 

Buffer overrun is a nonfatal error. The LPA11-K will 
automatically default to empty buffer 0 if a buffer overrun 
condition occurs. 


IND Returns the success or failure status as follows: 

0 = Error in call. Possible causes are the following: LPA$SETIBF 
subroutine was not previously called; LPASRLSBUF subroutine was not 
previously called; size of data buffers disagrees with the size computed 
by the LPA$SETIBF subroutine call. 

1 = successful sweep started 
nnn = VMS status code 
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4.5.4 LPA$DISWP — Initiate Synchronous Digital Input Sweep 

The LPA$DISWP subroutine initiates digital input through a DR11-K. It is 
applicable in multirequest mode only. 


The format of the LPA$DISWP subroutine call is as follows: 

CALL LPA$DISWP (IBUF,LBUF,[NBUF],[MODE],[DWELL],[IEFN],- 
[LDELAY],[ICHN],[NCHN],[IND]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

MODE Specifies sampling options. The VMS operating system defines the 

following sampling option values: 

Value 

Meaning 

0 

Immediate start. This is the default value for MODE. 

512 

External trigger for DR11-K. (The LPA 11-K Laboratory 
Peripheral Accelerator User's Guide describes the use of 
external triggers.) 

1024 

Time stamped sampling with Clock B. The double word 
consists of one data word followed by the value of the 
internal LPA11-K 16-bit counter at the time of the sample 
(see Section 2.4.3 in the LPA 11-K Laboratory Peripheral 
Accelerator User's Guide). 

2048 

Event marking. (The LPA 11-K Laboratory Peripheral 
Accelerator User's Guide describes event marking.) 

4096 

Start method. If selected, the start method is digital input. 

If not selected, the start method is immediate. Multirequest 
mode only. 

16384 

Buffer overrun is a nonfatal error. The LPA11-K will 
automatically default to fill buffer 0 if a buffer overrun 
condition occurs. 


IND Returns the success or failure status as follows: 

0 = Error in call. Possible causes are the following: LPA$SETIBF 
subroutine was not previously called; LPA$RLSBUF subroutine was not 
previously called; size of data buffers disagrees with the size computed 
by the LPA$SETIBF subroutine call. 

1 = successful sweep started 
nnn = VMS status code 
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4 5 5 LPA$DOSWP — Initiate Synchronous Digital Output Sweep 

The LPA$DOSWP subroutine initiates digital output through a DR11-K. It is 
applicable in multirequest mode only. 


The format of the LPA$DOSWP subroutine call is as follows: 

CALL LPA$DOSWP (IBUF,LBUF,[NBUF],[MODE],[DWELL],[IEFN],- 
[LDELAY],[ICHN],[NCHN],[IND]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

MODE Specifies the sampling options. The VMS operating system defines 

the following values: 

Value 

Meaning 

0 

Immediate start. This is the default value for MODE. 

512 

External trigger for DR11-K. (The LPA 11-K Laboratory 
Peripheral Accelerator User's Guide describes the use of 
external triggers.) 

4096 

Start method. If selected, digital input start. If not selected, 
immediate start. 

16384 

Buffer overrun is a nonfatal error. The LPA 11-K will 
automatically default to empty buffer 0 if a buffer overrun 
condition occurs. 


IND Returns the success or failure status as follows: 

0 = Error in call. Possible causes are the following: LPA$SETIBF 
subroutine was not previously called; LPA$RLSBUF subroutine was not 
previously called; size of data buffers disagrees with the size computed 
by the LPA$SETIBF subroutine call. 

1 = successful sweep started 
nnn = VMS status code 


4.5.6 LPA$LAMSKS — Set LPA11 -K Masks and NUM Buffer 

The LPA$LAMSKS subroutine initializes a user buffer that contains a number 
to append to the logical name LPA11$, a digital start word mask, an event 
mark mask, and channel numbers for the two masks. 

The LPA$LAMSKS subroutine must be called in the following cases: 

• If users intend to use digital input starting or event marking 

• If users do not want to use the default of LAAO assigned to LPA11$0 

• If multiple LPAll-Ks are used 

The format of the LPA$LAMSKS subroutine call is as follows: 

CALL LPA$LAMSKS (LAMSKB,[NUM],[IUNIT],[IDSC],[IEMC],[IDSW],- 
[IEMW],[IND]) 
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Argument descriptions are as follows: 


LAMSKB 

NUM 

IUNIT 

IDSC 

IEMC 

IDSW 


Specifies a four-word array. 

Specifies the number appended to LPA11$. The sweep is 
started on the LPA11-K assigned to LPA11$num. 

Not used. This argument is present for compatibility only. 

Specifies the digital START word channel. Range is 0 through 4. 
The IDSC argument length is one byte. 

Specifies the event MARK word channel. Range is 0 through 4. 
The IEMC argument length is one byte. 

Specifies the digital START word mask. The IDSW argument 
length is one word. 


IEMW Specifies the event MARK word mask. The IEMW argument 

length is one word. 

,ND Always equal to 1 (success). This argument is present for 

compatibility only. 


4.5.7 


LPA$SETADC — Set Channel Information for Sweeps 

The LPA$SETADC subroutine establishes channel start and increment 
information for the sweep control subroutines (see Table 4-4). It must be 
called to initialize IBUF before the LPA$SETADC subroutine is called. 

The LPA$SETADC subroutine can be called in either of the following 
formats: 

CALL LPA$SETADC (IBUF,[IFLAG],[ICHN],[NCHN],[INC],[IND]) 
or 

IND=LP ASSET ADC (IBUF,[IFLAG],[ICHN],[NCHN],[INC]) 

Argument descriptions are as follows: 


IND 


IBUF 

IFLAG 

ICHN 


NCHN 

INC 


Returns the success or failure status as follows: 

0 = LPASSETIBF was not called prior to the LPASSETADC call 

1 = LPASSETADC call successful 

The IBUF array specified in the LPASSETIBF call. 

Reserved. This argument is present for compatibility only. 

Specifies the first channel number. Range is 0 through 255; 
default is 0. The ICHN argument length is one longword. 

If INC = 0, ICHN is the address of a random channel list. This 
address must be word aligned. 

Specifies the number of samples taken per sample sequence. 
Default is 1. 

Specifies the channel increment. Default is 1. If INC is 0, ICHN is 
the address of a random channel list. The INC argument length 
is one longword. 
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4.5.8 


LPA$SETIBF — Set IBUF Array for Sweeps 

The LPA$SETIBF subroutine initializes the IBUF array for use with the 
following subroutines: 


LPA$ADSWP 

LPASDOSWP 

LPA$INXTBF 

LPA$RMVBUF 


LPASDASWP 
LPASIBFSTS 
LPA$IWTBUF 
LP ASSET ADC 


LPASDISWP 

LPASIGTBUF 

LPASRLSBUF 

LPASSTPSWP 


The format of the LPA$SETIBF subroutine call is as follows 


CALL LPASSETIBF (IBUF,[IND],[LAMSKB],BUF0,[BUF1.BUF7]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

IBUF Specifies a 50-longword array that is initialized by this 

subroutine. IBUF must be longword-aligned. (See Table 4-5 
for additional information on IBUF.) 

IND Returns the success or failure status as follows: 

0 - Error in call. Possible causes are the following: incorrect 
number of arguments; IBUF array not longword-aligned; buffer 
addresses not equidistant. 

1 = IBUF initialized successfully 

LAMSKB Specifies the name of a four-word array. This array allows 

the use of multiple LPA11-Ks within the same program 
because the argument used to start the sweep is specified 
by the LPASLAMSKS subroutine call. (See Section 4.5.6 for a 
description of the LPASLAMSKS subroutine.) 

BUFO, . . . Specify the names of the buffers. A maximum of eight buffers 
can be specified. At least two buffers must be specified to 
provide continuous sampling. The LPA11-K driver requires that 
all buffers be contiguous. To ensure this, the LPASSETIBF 
subroutine verifies that all buffer addresses are equidistant. 
Buffers must be longword-aligned. 


4.5.9 LPASSTPSWP — Stop In-Progress Sweep 

The LPASSTPSWP subroutine allows you to stop a sweep that is in progress. 
The format of the LPASSTPSWP subroutine call is as follows: 

CALL LPASSTPSWP (IBUF,[IWHEN],[IND]) 
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Arguments are as described in Section 4.5.1.2, with the following additions: 

IBUF The IBUF array specified in the LPA$ADSWP, LPA$DASWP, 

LPA$DISWP, or LPA$DOSWP subroutine call that initiated the 
sweep. 

IWHEN Specifies when to stop the sweep. The VMS operating system 

defines the following values: 

0 = Abort sweep immediately. Uses the SCANCEL system 
service. This is the default sweep stop. 

1 = Stop sweep when the current buffer transaction is 
completed. (This is the preferred way to stop requests.) 

IND Receives a success or failure code in the standard VMS format: 

1 = Success 

nnn = VMS error code issued by the SCANCEL system service 

Note that, when the LPASSTPSWP subroutine is returned, the sweep cannot 
be stopped. If it is necessary to wait until the sweep has stopped, you can 
call the LPASIWTBUF subroutine in a loop until it returns IBUFNO = -1 (see 
Section 4.5.16). 


4.5.10 LPA$CLOCKA — Clock A Control 

The LPASCLOCKA subroutine sets the clock rate for Clock A. 

The format of the LPASCLOCKA subroutine call is as follows: 

CALL LPASCLOCKA (IRATE,IPRSET,[IND],[NUM]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

IRATE Specifies the clock rate. One of the following values must be 

specified: 


Value 

Meaning 

-1 

Direct-coupled Schmidt trigger 1. Used only for A/D 
sweeps in dedicated mode, that is, MODE = 512 (see 
Section 4.5.2). 

0 

Clock B overflow or no rate 

1 

1 MHz 

2 

100 kHz 

3 

10 kHz 

4 

1 kHz 

5 

100 Hz 

6 

Schmidt trigger 1 

7 

Line frequency 


IPRSET Specifies the clock preset value. Maximum of 16 bits. The 

LPASXRATE subroutine can be used to calculate this value. The 
clock rate divided by the clock preset value yields the clock 
overflow rate. 
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IND 

NUM 


Receives a success or failure code as follows: 

1 = Clock A set successfully 

nnn = VMS error code indicating an I/O error 

Specifies the number to be appended to the logical name 
LPA11$. The default value is 0. This subroutine sets Clock A 
on the LPA11-K assigned to LPA11$num. 


4.5.11 LPA$CLOCKB — Clock B Control 

The LPA$CLOCKB subroutine provides the user with control of the KW11-K 
Clock B. 

The format of the LPA$CLOCKB subroutine call is as follows: 

CALL LPASCLOCKB ([IRATE],IPRSET,MODE,[IND],[NUM]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 
IRATE Specifies the clock rate. One of the following values must be 


specified: 


Value 

Meaning 

0 

Stops Clock B 

1 

1 MHz 

2 

100 kHz 

3 

10 kHz 

4 

1 kHz 

5 

100 Hz 

6 

Schmidt trigger 3 

7 

Line frequency 


If IRATE is 0 (default), the clock is stopped and the IPRSET and 
MODE arguments are ignored. 

IPRSET Specifies the preset value by which the clock rate is divided to 

yield the overflow rate. Maximum of eight bits. Overflow events 
can be used to drive Clock A. The LPASXRATE subroutine can 
be used to calculate the IPRSET value. 

MODE Specifies options. The VMS operating system defines the 

following values: 

1 = Clock B operates in noninterrupt mode. 

2 = The feed B to A bit in the Clock B status register will be 
set (see Section 3.3 of the LPA 11-K Laboratory Peripheral 
Accelerator User's Guide). 

IND Receives a success or failure code as follows: 

1 = Clock B set successfully 

nnn = VMS error code indicating an I/O error 
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Specifies the number to be appended to the logical name 
LPA11$. The default value is 0. This subroutine sets Clock B on 
the LPA11-K assigned to LPA11$num. 


4.5.12 LPA$XRATE — Compute Clock Rate and Preset Value 

The LPA$XRATE subroutine computes the clock rate and preset value 
for the LPA$CLOCKA and LPASCLOCKB subroutines using the specified 
intersample interval (AINTRVL). 

The LPA$XRATE subroutine can be called in either of the following formats: 
CALL LPASXRATE (AINTRVL,IRATE,IPRSET,IFLAG) 
or 

ACTUAL=LPA$XRATE(AINTRVL,IRATE,IPRSET,IFLAG) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

AINTRVL Specifies the intersample time selected by the user. The time is 

expressed in decimal seconds. Data type is floating point. 

IRATE Receives the computed clock rate as a value from 1 through 5. 

IPRSET Receives the computed clock preset value. 

'FLAG If the computation is for Clock A, IFLAG is 0; if for Clock B, 

IFLAG is not 0 (the maximum preset value is 255). The IFLAG 
argument length is one byte. 

ACTUAL Receives the actual intersample time if called as a function. Data 

type is floating point. If there are truncation and round-off errors, 
the resulting intersample time can be different from the specified 
intersample time. Note that when the LPASXRATE subroutine 
is called from VAX FORTRAN IV-PLUS programs as a function, 
it must be explicitly declared a real function. Otherwise, the 
LPASXRATE subroutine defaults to an integer function. 

If AINTRVL is either too large or too small to be achieved, both IRATE and 
ACTUAL are returned to 0. 


4.5.13 LPA$IBFSTS — Return Buffer Status 

The LPASIBFSTS subroutine returns information on the buffers used in a 
sweep. 

The format of the LPASIBFSTS subroutine call is as follows: 

CALL LPASIBFSTS (IBUF.ISTAT) 


4-26 










Laboratory Peripheral Accelerator Driver 

4.5 High-Level Language Interface 


descriptions are as follows: 

The IBUF array specified in the call that initiated the sweep. 

Specifies a longword array with as many elements as there are 
buffers involved in the sweep (maximum of eight). LPA$IBFSTS 
fills each array element with the status of the corresponding 
buffer: 

+2 - Buffer in device queue. LPASRLSBUF has been called for 
this buffer. 

+1 ■* Buffer in user queue. The LPA11-K has filled (data input) or 
emptied (data output) this buffer. 

0 = Buffer is not in any queue. 

-1 - Buffer is in the in-use queue; that is, it is either being 
filled or emptied, or it is the next to be filled or emptied by the 
LPA11-K. 


4.5.14 LPA$IGTBUF — Return Buffer Number 

The LPA$IGTBUF subroutine returns the number of the next buffer to be 
processed by the application program, the buffer at the head of the user 
queue (see Figure 4-3). It should be called by a completion routine at AST 
level to determine the next buffer to process. If an event flag was specified 
in the start sweep call, the LPA$IWTBUF, not the LPA$IGTBUF subroutine, 
should be called. 

The LPA$IGTBUF subroutine can be called in either of the following 
formats: 

CALL LPASIGTBUF (IBUF,IBUFNO) 

IBUFNOLPA$IGTBUF(IBUF) 

Arguments are as described in Section 4.5.1.2, with the following additions: 
IBUF The IBUF array specified in the call that initiated the sweep. 

IBUFNO Returns the number of the next buffer to be filled or emptied by 

the application program. 

Table 4-6 lists the possible combinations of IBUFNO and IOSB contents on 
the return from a call to the LPASIGTBUF subroutine. The first four words 
of the IBUF array contain the I/O status block (IOSB). If IBUFNO is -1, the 
IOSB must be checked to determine the reason. 


Argument 

IBUF 

ISTAT 
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Table 4-6 LPA$IGTBUF Call — IBUFNO and IOSB Contents 


IBUFNO 

IOSB(1) 

IOSB(2) 

IOSB{3),(4) 

Meaning 

n 

0 

(byte 

count) 

0 

Normal buffer 
complete. 

-1 

0 

0 

0 

No buffers in queue. 
Request still active. 

-1 

1 

0 

0 

No buffers in queue. 
Sweep terminated 
normally. 

-1 

VMS 

error 

code 

0 

LP A11 -K ready- 
out and main¬ 
tenance regis¬ 
ters (only if 
SSSDEVREQERR 
SS$_CTRLERR, or 
SSSDEVCMDERR 
is returned) 

No buffers in 
queue. Sweep 
terminated due to 
error condition. 

Section 4.6 describes 
the VMS error codes; 
Appendix A of the 

LPA 11-K Laboratory 
Peripheral Accelerator 
User's Guide lists the 
LPA11-K error codes. 


LPA$INXTBF — Set Next Buffer to Use 

The LPA$INXTBF subroutine alters the normal buffer selection algorithm so 
that you can specify the next buffer to be filled or emptied. The specified 
buffer is reinserted at the head of the device queue. 

The LPA$INXTBF subroutine can be called in either of the following formats: 
CALL LPA$INXTBF (IBUF,IBUFNO,IND) 

IND=LPA$INXTBF(IBUF,IBUFNO) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

The IBUF array specified in the call that initiated the sweep. 

Specifies the number of the next buffer to be filled or emptied. 
The buffer must already be in the device queue. 

Returns the result of the call as follows: 

0 = Specified buffer not in the device queue 
1 = Next buffer successfully set 


IBUF 

IBUFNO 

IND 
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4.5.16 LPA$IWTBUF — Return Next Buffer or Wait 

The LPA$IWTBUF subroutine returns the next buffer to be processed by the 
application program, the buffer at the head of the user queue. If the user 
queue is empty, the LPA$IWTBUF subroutine waits until a buffer is available. 
If a completion routine was specified in the call that initiated the sweep, the 
LPA$IGTBUF, not the LPA$IWTBUF subroutine, should be called. 

The LPA$IWTBUF subroutine can be called in either of the following 
formats: 

CALL LPA$IWTBUF (IBUF,[IEFN],IBUFNO) 

IBUFNO=LPA$IWTBUF(IBUF,[IEFN]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

IBUF The IBUF array specified in the call that initiated the sweep. 

IEFN Not used. This argument is present to provide compatibility with 

the operating system. (The event flag is the one specified in the 
start sweep call.) 

IBUFNO Returns the number of the next buffer to be filled or emptied by 

the application program. 

Table 4-7 lists the possible combinations of IBUFNO and I/O status block 
contents on the return from a call to the LPA$IWTBUF subroutine. The first 
four words of the IBUF array contain the I/O status block. If IBUFNO is —1, 
the I/O status block must be checked to determine the reason. 


Table 4-7 LPA$IWTBUF Call — IBUFNO and IOSB Contents 


IBUFNO 

IOSB(1) 

IOSB(2) 

IOSB(3),(4) 

Meaning 

n 

0 

(byte 

count) 

0 

Normal buffer 
complete. 

-1 

1 

0 

0 

No buffers in queue. 
Sweep terminated 
normally. 

-1 

VMS 

error 

code 

0 

LPA11-K ready- 
out and main¬ 
tenance regis¬ 
ters (only if 
SS$_DEVREQERR 
SS$_CTRLERR, or 
SS$_DEVCMDERR 
is returned) 

No buffers in 
queue. Sweep 
terminated due to 
error condition. 
Section 4.6 describes 
the VMS error codes; 
Appendix A of the 
LPA 11-K Laboratory 
Peripheral Accelerator 
User's Guide lists the 
LPA11-K error codes. 


4.5.17 LPA$RLSBUF — Release Data Buffer 

The LPA$RLSBUF subroutine declares one or more buffers available to be 
filled or emptied by the LPA11-K. It inserts the buffer at the tail of the device 
queue (see Figure 4-3). 
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The format of the LPA$RLSBUF subroutine call is as follows: 

CALL LPA$RLSBUF (IBUF,[IND],INDEXO,INDEX 1.INDEXN) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

IBUF The IBUF array specified in the call that initiated the sweep. 

IND Returns the success or failure status as follows: 

0 = Buffer number was illegal, the number of arguments 
specified was incomplete, or a double buffer overrun occurred. 
A double buffer overrun can occur only if buffer overrun was 
specified as a nonfatal error, a buffer overrun occurs, and 
buffer 0 was not released (probably on the user queue after a 
previous buffer overrun). 

1 = Buffer(s) released successfully. 

INDEXO, . . . Specify the indexes (0-7) of the buffers to be released. A 

maximum of eight indexes can be specified. 

The LPA$RLSBUF subroutine must be called to release a buffer (or buffers) 
to the device queue before the sweep is initiated. (See Section 4.5.1.1 for a 
discussion of buffer management.) Note that the LPA$RLSBUF subroutine 
does not verify whether the specified buffers are already in a queue. If 
a buffer is released when it is already in a queue, the queue pointers are 
invalidated and unpredictable results can occur. 

If buffer overrun is specified as a nonfatal error, buffer 0 should not be 
released before the sweep is initiated. However, if either the LPA$IGTBUF or 
LPA$IWTBUF subroutine returns buffer 0, it should be released. In this case, 
buffer 0 is set aside (not placed on a queue) until the buffer overrun occurs. 

If a buffer overrun occurs and buffer 0 was not released, the LPA$RLSBUF 
subroutine returns an error the next time buffer 0 is released. 


4.5.18 LPA$RMVBUF — Remove Buffer from Device Queue 

The LPA$RMVBUF subroutine removes a buffer from the device queue. 

The format of the LPA$RMVBUF subroutine call is as follows: 

CALL LPA$RMVBUF (IBUF,IBUFNO,[IND]) 

Arguments are as described in Section 4.5.1.2, with the following additions: 

IBUF The IBUF array specified in the call that initiated the sweep. 

IBUFNO Specifies the number of the buffer to remove from the device 

queue. 

IND Returns the success or failure status as follows: 

0 = Buffer not found in the device queue 
1 = Buffer successfully removed from the device queue 
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4.5.19 LPA$CVADF — Convert A/D Input to Floating-Point 

The LPA$CVADF subroutine converts A/D input values to floating-point 
numbers. It is supported to provide compatibility with the VMS operating 
system. 

The LPA$CVADF subroutine can be called in either of the following formats: 
CALL LPASCVADF (IVAL,VAL) 

VAL=LPA$CVADF(IVAL) 

Argument descriptions are as follows: 

IVAL Contains the value (bits 11:0) read from the A/D input. Bits 

15:12 are 0. 

VAL Receives the floating-point value. 

4.5.20 LPA$FLT16 — Convert Unsigned 16-bit Integer to Floating-Point 

The LPA$FLP16 subroutine converts unsigned 16-bit integers to floating 
point. It is supported to provide compatibility with the VMS operating 
system. 

The LPA$FLT16 subroutine can be called in either of the following formats: 
CALL LPA$FLT 16 (IVAL,VAL) 

VAL=LPA$FLT 16(1 VAL) 

Argument descriptions are as follows: 

IVAL An unsigned 16-bit integer. 

VAL Receives the converted value. 

4.5.21 LPA$LOADMC — Load Microcode and Initialize LPA11 -K 

The LPA$LOADMC subroutine provides a program interface to the LPA11-K 
microcode loader. It sends a load request through a mailbox to the loader 
process to load microcode and to initialize an LPA11-K. (Section 4.7.1 
describes the microcode loader process.) 

The format of the LPA$LOADMC subroutine call is as follows: 

CALL LPASLOADMC ([ITYPE][,NUM][,IND][,IERROR]) 
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Argument descriptions are as follows: 

ITYPE The type of microcode to be loaded. The VMS operating system 

defines the following values: 


Value 

Meaning 

1 

Multirequest mode; default value 

2 

Dedicated A/D mode 

3 

Dedicated D/A mode 


NUM The number to be appended to the logical name LPA11$. The 

default value is 0. 

IND Receives the completion status as follows: 

1 = Microcode loaded successfully 
nnn = VMS error code 

IERROR Provides additional error information. Receives the second 

longword of the I/O status block if SS$_CTRLERR, 
SS$_DEVCMDERR, or SS$_DEVREQERR is returned in IND. 
Otherwise, the contents of IERROR are undefined. 


4.6 I/O Status Block 


The I/O status block (IOSB) format for the load microcode, start 
microprocessor, initialize LPA11-K, set clock, and start data transfer request 
QIO functions is shown in Figure 4-4. 

Figure 4-4 I/O Functions IOSB Content 


31__ 16 15 o 


byte count 

status 

LPAll-K 

maintenance status 

LPAll-K ready-out 


ZK-662-82 


VMS status values and the byte count are returned in the first longword. 
Status values are defined by the $SSDEF macro. The byte count is the 
number of bytes transferred by a IO$__LOADMCODE request. If 
SS$__CTRLERR, SS$_DEVCMDERR, or SS$_DEVREQERR is returned in 
the status word, the second longword contains the LPA11-K ready-out 
register and LPA11-K maintenance status register values present at the 
completion of the request. The high byte of the ready-out register contains 
the specific LPA11-K error code (see Appendix A of the LPAll-K Laboratory 
Peripheral Accelerator User's Guide). Appendix A of this manual lists the status 
returns for LPAll-K I/O functions. (The VMS System Messages and Recovery 
Procedures Reference Volume provides explanations and suggested user actions 
for these returns.) 
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If high-level language library procedures are used, the status returns listed in 
Appendix A can be returned from the resultant QIO functions. Since buffers 
are filled by these procedures asynchronously, two I/O status blocks are 
provided in the IBUF array: one for the high-level language procedures and 
one for the LPA11-K driver. The first four words of the IBUF array contain 
the I/O status block for the high-level language procedures. 


4.7 Loading LPA11 -K Microcode 

The microcode loading and device initialization routines automatically 
load microcode during system initialization (if specified in the system 
manager's startup file) and during power recovery. These routines also 
allow a nonprivileged user to load microcode and to restart the system. 

The LPA11-K loader and initialization routines consist of the following parts: 

• A microcode loader process that loads any of the three microcode 
versions, initializes the LPA11-K, and sets the clock rate. Loading is 
initiated by either a mailbox request or a power recovery AST. This 
process requires permanent mailbox (PRMMBX) and physical I/O 
privileges. 

• An operator process that accepts operator commands or indirect file 
commands to load microcode and to initialize an LPA11-K. This process 
uses a mailbox to send a load request to the loader process; temporary 
mailbox (TMPMBX) privilege is required. 

• An LPA11-K procedure library routine that provides a program interface 
to the LPA11-K microcode loader. The procedure sends a load request 
through a mailbox to the loader process to load microcode and to initialize 
an LPA11-K. Section 4.5.21 describes that routine in greater detail. 


4.7.1 Microcode Loader Process 

The microcode loader process loads microcode, initializes a specific LPA11-K, 
and sets the clock at the default rate (10 kHz interrupt rate). A bit set in 
a controller bit map indicates that the specified controller was loaded. The 
process specifies a power recovery AST, creates a mailbox whose name 
(LPA$LOADER) is entered in the system logical name table, and then 
hibernates. 

The correct device configuration is determined automatically. When LPA11-K 
initialization is performed, every possible device (see Table 4-1) is specified as 
present on the LPA11-K. If the LPA11-K returns a "device not found" error, 
the LPA11-K is reinitialized with that device omitted. 

On receipt of a power recovery AST, the loader process examines the 
controller bit map to determine which LPAll-Ks have been loaded. For 
each LPA11-K, the loader process performs the following functions: 

• Obtains device characteristics 

• Reloads the microcode previously loaded 

• Reinitializes the LPA11-K 

• Sets Clock A to the previous rate and preset value 
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4.7.2 Operator Process 

The operator process loads microcode and initializes an LPA11-K through 
either terminal or indirect file commands. To run the operator process, type 
RUN SYS$SYSTEM:LALOAD. The command input syntax is as follows: 

devname/type 

devname is the device name of the LPA11-K to be loaded. A logical name 
can be specified. However, only one level of logical name translation is 
performed. If devname is omitted, LAAO is the default name. If /type appears, 
it specifies one of the following types of microcode to load: 

• /MULTI —REQUEST—Multirequest mode 

• /ANALOG —DIGITAL—Dedicated A/D mode 

• /DIGITAL—ANALOG—Dedicated D/A mode 

If /type type is omitted, /MULTI —REQUEST is the default. 

After receiving the command, the operator process formats a message and 
sends it to the loader process. Completion status is returned through a return 
mailbox. 


4.8 RSX—11 M/M—PLUS and VMS Differences 

This section lists those areas of the VMS high-level language support routines 
that differ from the RSX-11M LPA11-K routines. The RSX-UM-PLUS 
and Micro/RSX I/O Drivers Manual provides a detailed description of 
the RSX-11M LPA11-K support routines. Differences between the VMS 
and RSX-11M/M-PLUS routines can be determined by comparing the 
descriptions in the RSX-UM-PLUS and Micro/RSX I/O Drivers Manual with 
the descriptions for the VMS routines in the preceding sections of this chapter. 


4.8.1 General 

The following are general features of VMS high-level support routines: 

• The LUN argument is not used. The NUM argument specifies the number 
to be appended to the logical name LPA11$. 

• All routine names have the prefix LPA$. 

• In the LPA$SETIBF routine, buffer addresses are checked for contiguity. 

• In the LPA$LAMSKS routine, the IUNIT argument is not used. 

• In the LPA$IWTBUF routine, the IEFN argument is not used. The event 
flag specified in the sweep routine is used. 

• The combinations of IBUFNO and I/O status block (IOSB) values 
returned by the LPA$IWTBUF and LPA$IGTBUF subroutines are 
different. 
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4.8.2 Alignment and Length 

The following are features of alignment and length in VMS high-level support 
routines: 

• Buffers must be contiguous. 

• Buffers must be longword-aligned. 

• The random channel list (RCL) must be word-aligned. 

• The IBUF array length is 50 longwords and must be longword-aligned. 


4.8.3 Status Returns 

The following are features of status returns in VMS high-level support 
routines: 

• The I/O status block (IOSB) length is eight bytes; numeric values of 
errors differ. 

• Several routines return the following: 

1 = Success 

0 = Failure detected in support routine 

nnn = VMS status code; failure detected in system service 


4.8.4 Sweep Routines 

The following are features of sweep routines in VMS high-level support 
routines: 

• If an event flag is specified, it must be within a %VAL() construction. 

• A tenth argument, IND, is added to return the success or failure status. 


4.9 Programming Examples 

The following programming examples use LPA11-K high-level language 
procedures and LPA11-K Queue I/O functions. 

The VMS Device Support Manual volume contains information that is 
applicable to LPA11-K programming. 
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4.9.1 LPA11 -K High-Level Language Program (Program A) 

This sample program (Example 4-1) is an example of how the LPA11-K high- 
level language procedures perform an A/D sweep using three buffers. The 
program uses default arguments whenever possible to illustrate the simplest 
possible calls. The program assumes that dedicated mode microcode has 
previously been loaded into the LPA11-K. Table 4-8 lists the variables used 
in this program. 

Table 4-8 Program A Variables 

Variable Description 


BUFFER The data buffer array. BUFFER is a common area to guarantee 

longword alignment. 

IBUF The LPA11-K high-level language procedures use the IBUF array 

for local storage. 

BUFNUM BUFNUM contains the buffer number returned by LPA$IWTBUF. 

In this example, the possible values are 0, 1, and 2. 

ISTAT 1STAT contains the status return from the high-level language 

calls. 


Example 4-1 LPA11 -K High-Level Language Program (Program A) 


c ********************************************************^^*** ++++ 
c 

c PROGRAM A 

C 

C ***************************************************************** 

INTEGER*2 BUFFER(1000,0:2),I0SB(4) 

INTEGER*4 IBUF(50),ISTAT,BUFNUM 

C0MM0N/AREA1/BUFFER 

EQUIVALENCE (I0SB(1),IBUF(l)) 

C 

C Set clock rate to 1 khz, clock preset to -10. 

C 

CALL LPA$CL0CKA(4,-10,ISTAT) 

IF (.NOT. ISTAT) GO TO 950 
C 

C Initialize IBUF array for sweep. 

C 

CALL LPA$SETIBF(IBUF,ISTAT,.BUFFER(1,0).BUFFER(1,1),BUFFER(1 2)) 
IF (.NOT. ISTAT) GO TO 950 
C 

C Release all the buffers. Note use of buffer numbers rather than 
C buffer names. 

C 

CALL LPA$RLSBUF(IBUF,ISTAT.0,1,2) 

IF (.NOT. ISTAT) GO TO 950 


Example 4-1 Cont'd. on next page 
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Example 4-1 (Cont.) LPA11-K High-Level Language Program 

(Program A) 


c 

C Start A/D sweep 
C 

CALL LPA$ADSWP(IBUF,1000,50..ISTAT) 

IF (.NOT. ISTAT) GO TO 950 
C 

C Get next buffer filled with data. If BUFNUM is negative, there 
C are no more buffers and the sweep is stopped. 

C 

100 BUFNUM = LPA$IWTBUF(IBUF) 

IF (BUFNUM .LT. 0) GO TO 800 
C 

C Process data in buffer (1,BUFNUM) to buffer (1000,BUFNUM). 


(Application-dependent code is inserted at this point.) 


C Release buffer is filled again. 

C 

200 CALL LPASRLSBUF(IBUF,ISTAT,BUFNUM) 

IF (.NOT. ISTAT) GO TO 950 
GO TO 100 

C 

C There are no more buffers to process. Check to ensure that the 

C sweep ended successfully. I0SB(1) contains either 1 or a 

C VMS status code. 

C 

800 IF (.NOT. I0SB(1)) CALL LIB$ST0P(*/.VAL(I0SB(1))) 

PRINT *.'SUCCESSFUL COMPLETION 1 
GO TO 2000 

C 

C Error return from subroutine. ISTAT contains either 0 or a 

C VMS error code. 

C 

950 IF (ISTAT .NE. 0) CALL LIBSSTOPC/.VAL(ISTAT)) 

PRINT *.'ERROR IN LPAli-K SUBROUTINE CALL' 

2000 STOP 

END 

C ****************************************************************** 


4.9.2 LPA11 -K High-Level Language Program (Program B) 

This program (Example 4-2) is a more complex example of LPA11-K 
operations performed by the LPA11-K high-level language procedures. 
The following operations are demonstrated: 

• Program-requested loading of LPA11-K microcode 

• Setting the clock at a specified rate 

• Use of nondefault arguments whenever possible 

• An A/D sweep that uses an event flag 

• A D/A sweep that uses a completion routine 
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• Buffer overrun set (buffer overrun is a nonfatal error) 

• Random channel list (RCL) addressing 

• Sequential channel addressing 

Table 4-9 lists the variables used in this program. 


Table 4-9 

Program B Variables 

Variable 

Description 

AD 

An array of buffers for ahA/D sweep (8 buffers of 500 words 
each) 

DA 

An array of buffers for a D/A sweep (2 buffers of 2000 words 
each) 

IBUFAD 

The IBUF array for an A/D sweep 

IBUFDA 

The IBUF array for a D/A sweep 

RCL 

The array that contains the random channel list (RCL) 

ADIOSB 

The array that contains the I/O status block for the A/D sweep. 
Equivalenced to the beginning of IBUFAD 

DAIOSB 

The array that contains the I/O status block for the D/A sweep. 
Equivalenced to the beginning of IBUFDA 

ISTAT 

Contains the status return from the high-level language calls 


Example 4—2 LPA11-K High-Level Language Program (Program B) 

c ******************************************************************* 

c 

c Program B 

C 

C ******************************************************************* 

EXTERNAL FILLBF 
REAL*4 LPASXRATE 

INTEGER*2 AD(500.0:7).DA(2000,0:1).RCL(5).MODE,IPRSET 
INTEGER*2 ADI0SB(4),DAI0SB(4) 

INTEGER*4 IBUFAD(50),IBUFDA(50),LAMSKB(2) 

INTEGER*4 ISTAT,IERROR.IRATE,BUFNUM 

REAL*4 PERIOD 

COMMON /SWEEP/ AD, DA, IBUFAD, IBUFDA 

EQUIVALENCE (IBUFAD(l).ADIOSB(l)).(IBUFDA(l),DAI0SB(1)) 

PARAMETER MULTI=1, HBIT='8000'X. LSTCHN=HBIT+7 
C 

C Set up random channel list. Note that the last word must have bit 
C 15 set. 

C 

DATA RCL/2.6.3.4.LSTCHN/ 

Example 4-2 Cont'd. on next page 
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Example 4-2 (Cont.) LPA11 -K High-Level Language Program 

(Program B) 

0 ******************************************************************* 

c 

C Load multirequest mode microcode and set the clock overflow rate 
C to 5 khz. 

C 

0 ******************************************************************* 
C 

c Load microcode on LPA11-K assigned to LPA11$3. 

C 

CALL LPA$LOADMC(MULTI,3,ISTAT,IERROR) 

IF (.NOT. ISTAT) GO TO 5000 
C 

C Compute clock rate and preset. Set clock 'A' on LPA11-K 
C assigned to LPA11$3. 

C 

PERIOD = LPA$XRATE(.0002,IRATE,IPRSET.O) 

IF (PERIOD .EQ. 0.0) GO TO 5500 

CALL LPA$CLOCKA(IRATE,IPRSET,ISTAT,3) 

IF (.NOT. ISTAT) GO TO 5000 

C ******************************************************************* 

c 

C Set up for A/D sweep 
C 

q ******************************************************************* 
C 

C Initialize IBUF array. Note the use of the LAMSKB argument because 
C the LPA11-K assigned to LPA11$3 is used. 

q 

CALL LPA$SETIBF(IBUFAD.ISTAT,LAMSKB.AD(1,0),AD(1,1),AD(1,2), 

1 AD(1.3).AD(1.4).AD(1.5),AD(1,6),AD(1.7» 

IF (.NOT. ISTAT) GO TO 5000 

CALL LPA$LAMSKS(LAMSKB,3) 

C . 

C Set up random channel list sampling (20 samples in a sample 

C sequence). 

C 

CALL LPA$SETADC(IBUFAD,,RCL,20,0,ISTAT) 

IF (.NOT. ISTAT) GO TO 5000 
C 

C Release buffers for A/D sweep. Note that buffer 0 is not 
C released because buffer overrun will be specified as nonfatal. 

C 

CALL LPA$RLSBUF(IBUFAD,ISTAT.1,2,3,4,5.6,7) 

IF (.NOT. ISTAT) GO TO 5000 


Example 4-2 Cont'd. on next page 
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Example 4-2 (Cont.) LPA11 -K High-Level Language Program 

(Program B) 


C *********************************** j|c * 3|cj|cj|c + + * + + + + 3(c3|c5|cj|ej|cj|csjcjje3)e3|ej|cj|{3jcjjejjcjjt + 3(cj|c + 

c 

C Set up for D/A sweep 
C 

C ******************************************************************* 

c 

C Note that the same LAMSKB array can be used because the LAMSKB 
C contents apply to both A/D and D/A sweeps. 

C 

CALL LPA$SETIBF(IBUFDA,ISTAT,LAMSKB,DA(1,0),DA(1,1)) 

IF (.NOT. ISTAT) GO TO 5000 
C 

C Set up sampling parameters as follows: initial channel = 1. 

C Number of channels sampled each sample sequence = 2, channel 
C increment = 2, that is, sample channels 1 and 3 each sample 
C sequence. 

C 

CALL LPA$SETADC(IBUFDA,,1,2,2,ISTAT) 

IF (.NOT. ISTAT) GO TO 5000 
C 

C Fill buffers with data for output to D/A. 


(Application-dependent code is inserted here to fill buffers 

DA(1,0) through DA(2000,0) and DA(1,1) through DA(2000,1) with data). 


C 

C Release buffers for D/A sweep. 

C 

CALL LPASRLSBUF (IBUFDA,ISTAT,0,1) 
IF (.NOT. ISTAT) GO TO 5000 

Example 4—2 Cont'd. on next page 
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Example 4-2 (Cont.) LPA11-K High-Level Language Program 

(Program B) 


Q ***************************************************************** 

c 

C Start both sweeps 
C 

q ***************************************************************** 

C 

C Start A/D sweep. Mode bits specify buffer overrun is nonfatal and 
C multirequest mode. Sweep arguments specify 500 samples/buffer, 

C Indefinite sampling, dwell = 10 clock overflows, synchronize using 
C event flag 15, and a delay of 50 clock overflows. 

C 

MODE = 16384 + 64 

CALL LPA$ADSWP(IBUFAD,500.0,MODE, 10,y,VAL(15) ,50, , .ISTAT) 

IF (.NOT. ISTAT) GO TO 5000 
C 

C Start D/A sweep. Mode specifies multirequest mode. Other 
C arguments specify 2000 samples/buffer, fill 15 buffers, dwell = 25 
C clock overflows, synchronize by calling the completion routine 
C 'FILLBF', and delay = 10 clock overflows. (See the FILLBF listing 
C after the program B listing.) 

C 

MODE = 64 

CALL LPA$DASWP(IBUFDA,2000,15,MODE,25.FILLBF,10,,,ISTAT) 

(.NOT. ISTAT) GO TO 5000 

0 ******************************************************************* 
C n/ . 

C Wait for an A/D buffer and then process the data it contains. D/A 
C buffers are filled asynchronously by the completion routine FILLBF. 

C 

0 ******************************************************************* 
C 

C Wait for a buffer to be filled by A/D. If BUFNUM is less than 
C zero, the sweep has stopped (either successfully or with an error). 

C 

100 BUFNUM = LPA$IWTBUF(IBUFAD) 

IF (BUFNUM .LT. 0) GO TO 1000 

There is A/D data in AD(1.BUFNUM) through AD(500,BUFNUM) 


(Process the A/D data with the application-dependent code inserted 
here.) 


Example 4-2 Cont'd. on next page 
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Example 4-2 (Cont.) LPA11-K High-Level Language Program 

(Program B) 


c 

C Assume sweep should be stopped when the last sample in buffer 
C equals 0. Note that the sweep actually stops when the buffer 
C currently being filled is full. Also note that LPA$IWTBUF 
C continues to be called until there are no more buffers to process. 

IF (AD(500,BUFNUM) .NE. 0) GO TO 200 
CALL LPASSTPSWP(IBUFAD,1,ISTAT) 

IF (.NOT. ISTAT) GO TO 5000 

C 

C After the data is processed, the buffer is released to be 
C filled again. Then the next buffer is obtained from A/D 
C 

200 CALL LPASRLSBUF(IBUFAD,ISTAT,BUFNUM) 

IF (.NOT. ISTAT) GO TO 5000 
GO TO 100 

C 

C Enter here when A/D sweep has ended. Check for error or 
C successful end. (Note: Assume that the D/A sweep has already 
C ended - see completion routine FILLBF.) 

C 

1000 IF(ADI0SB(1)) GO TO 6000 

CALL LIB$ST0P ( # /*VAL (ADIOSB (1) ) ) 

C 

C Enter here if there was an error returned from one of the 
C LPA11-K high-level language calls. ISTAT contains either 0 
C or a VMS status code. 

C 

5000 IF (ISTAT .NE. 0) CALL LIB$ST0P ( # /.VAL(ISTAT)) 

5500 PRINT *,'ERROR IN LPA11-K SUBROUTINE CALL' 

GO TO 7000 

6000 PRINT *,'SUCCESSFUL COMPLETION' 

7000 STOP 

END 

C ******************************************************************* 

c 

C Subroutine FILLBF 
C 

C ******************************************************************* 

c 

C The FILLBF subroutine is called whenever the D/A has emptied a 
C buffer, and that buffer is available to be refilled. This 
C subroutine gets the buffer, fills it, and releases it back to the 

C LPA11-K. Note that the D/A sweep is stopped automatically after 

C 15 buffers have been filled. Also note that FILLBF is called by 
C an AST handler. It is therefore called asynchronously from the 

C main program at AST level. Care should be exercised when accessing 

C variables that are common to both levels. 

C 

INTEGER*2 AD(500,0:7),DA(2000,0:1),DAI0SB(4) 

INTEGER*4 IBUFAD(50),IBUFDA(50).BUFNUM,ISTAT 
EQUIVALENCE (IBUFDA(l).DAIOSB(l)) 

COMMON /SWEEP/AD,DA,IBUFAD,IBUFDA 


Example 4-2 Cont'd. on next page 
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Example 4-2 (Cont.) LPA11-K High-Level Language Program 

(Program B) 


c 

C Get buffer number of next buffer to fill. 
C 

BUFNUM = LPA$IGTBUF(IBUFDA) 

IF (BUFNUM .LT. 0) GO TO 3000 

C 

C Fill buffer with data for output to D/A. 


(Application-dependent code is inserted here to fill buffer 
DA(1,BUFNUM) through DA(2000.BUFNUM) with data.) 


C 

C Release buffer 
C 

CALL LPA$RLSBUF(IBUFDA.ISTAT.BUFNUM) 

GO TO 4000 

C 

C Check for successful end of sweep. 

C 

3000 IF(DAI0SB(1)) GO TO 4000 

C 

C Error in sweep 
C 

CALL LIB$ST0P ( # /,VAL (DAIOSB (1) ) ) 

4000 RETURN 

END 

C ******************************************************************* 


4.9.3 LPA11 -K QIO Functions Program (Program C) 

This sample program (Example 4-3) uses QIO functions to start an A/D 
data transfer from an LPA11-K. (The program assumes multirequest mode 
microcode has been loaded.) Sequential channel addressing is used. The 
data transfer is stopped after 100 buffers have been filled; no action is taken 
with the data as the buffers are filled. Note that this program starts the data 
transfer and then waits until the QIO operation completes. 
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Example 4—3 LPA11-K QIO Functions Program (Program C) 


******************************************************************* 

Program C 

******************************************************************* 

•TITLE LPA11-K EXAMPLE PROGRAM 
.IDENT /V01/ 

•PSECT LADATA,LONG 


IOSB: 

.BLKQ 

1 

COUNT: 

• LONG 

0 

CBUFF: 




.WORD 

~X20A 


• WORD 

3 


.LONG 

USW 


.LONG 

4000 


.LONG 

DATA.BUFFERO 

.LONG 

0 


.LONG 

0 


.WORD 

10 


.BYTE 

0 


.BYTE 

1 


.WORD 

16 


.WORD 

1 


.BYTE 

0 


.BYTE 

0 


.WORD 

0 


.WORD 

0 


.WORD 

0 


USW: .WORD 

0 


.ALIGN 

LONG 


DATA.BUFFERO: 

. BLKW 

500 

DATA.BUFFERl: 

. BLKW 

500 

DATAJBUFFER2: 

.BLKW 

500 

DATA.BUFFER3: 

.BLKW 

500 


I/O status block 
Count of buffers filled 

Command buffer for start 
Data QIO 

Mode = Sequential channel 
Addressing, A/D, 
multirequest mode 
Valid buffer mask 
(4 buffers) 

User Status Word address 
Aggregate buffer length 
Address of data buffers 
No random channel list 
length 

No random channel list 

address 

Delay 

Start channel 
Channel increment 
Number of samples in 
sample sequence 
Dwell 

Start word number 

Event mark word 

Start word mask 

Event mark mask 

Fills out command buffer 

User Status Word 

Buffers must be 
longword aligned 
Data buffers 


Example 4-3 Cont'd. on next page 


4-44 













Laboratory Peripheral Accelerator Driver 

4.9 Programming Examples 


Example 4-3 (Cont.) LPA11 -K QIO Functions Program (Program C) 


DEVNAME: .ASCID /LAAO/ 

CHANNEL: .BLKW 1 ; Contains channel number 


.PSECT LACODE,NOWRT 


START: 


5$: 


.ENTRY START, ~m<> 

$ASSIGN_S DEVNAM=DEVNAME,CHAN=CHANNEL 


Assign channel 


BLBS 

BRW 


R0,5$ 

ERROR 


$QI0W_S ,CHAN=CHANNEL,FUNC=#I0$_ 
I0SB=I0SB,,,,P2=#1,P3=#~ 
BLBC RO,ERROR 

MOVZWL IOSB.RO 

BLBC RO,ERROR 

CLRW USW 

MOVL #100,COUNT 

$QI0W_S ,CHANNEL,#IO$_STARTDATA, 
I0SB=I0SB,,,P1=CBUFF,P2= 
BLBC RO,ERROR 


No error 
Error 

Set clock overflow rate 
To 2 khz. (1 mhz rate 
divided by 500 preset) 
SETCLOCK,- 
X143,P4#-500 
Error 

Pick up I/O status 
Error 

Start data transfer 
Clear USW (start with 
buffer 0) 

Fill 100 buffers 

#40,P3=#BFRAST 
; Error 


; Note that the QIO waits until it finishes. Normally, the data is 
• processed here as the buffers are filled. Check for error when 


; the QIO completes. 

MOVZWL IOSB.RO 
BLBC RO,ERROR 
RET 

ERROR: 


PUSHL 

RO 

CALLS 

#1,G*LIB$ST0P 

BFRAST: BFRAST,m' 

•<> 

.WORD 

0 

INCB 

USW+1 

CMPZV 

#0,#3,USW+1,#3 

BLEQ 

10$ 

CLRB 

USW+1 

10$: DECL 

COUNT 

BGTR 

20$ 

BISB 

#*X40,USW+1 

20$: BICB 

#'X80.USW+1 

RET 


.END 

START 


Pick up I/O status 
Error 

All done - exit 

Enter here if error 
status in RO 
Push onto stack 
Signal error 

Buffer AST routine 
BFRAST is called whenever 
a buffer is filled 

; Add 1 to buffer number 
; Handle wraparound 

; Use buffer 0 
; Decrement buffer count 

; Enough buffers filled - 
; Set stop bit 
; Clear done bit 


• ******************************************************************* 
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Line Printer Driver 


This chapter describes the use of the line printer drivers LPDRIVER and 
LCDRIVER. 


5.1 Supported Line Printer Devices 

The following sections describe the line printer controllers and line printers 
supported by the VMS operating system. 


5.1.1 LP11 Line Printer Controller 

The LP11 line printer controller provides an interface between the 

VAX UNIBUS adapter and the line printer. The LP11 performs the following 

functions: 

• Synchronizes single-character data transfers from the UNIBUS to the 
printer 

• Informs the VMS operating system about printer status 

• Enables the printer to gain control of the UNIBUS to report interrupts 


5.1.2 DMF32 and DMB32 Line Printer Controllers 

The DMF32 and DMB32 line printer controllers provide a direct memory 
access (DMA) interface between the VAX UNIBUS adapter (for the DMF32), 
or the VAXBI adapter (for the DMB32), and the line printer. The 
DMF32/DMB32 optionally perform the following functions: 

• Tab expansion 

• Carriage control 

• Line wrapping and truncation 

• Case conversion 

• Passall mode 

• Printall mode 


5.1.3 LP27 Line Printer 

The LP27 line printer is a high-speed, 132-column line printer, available with 
either a 64- or 96-character ASCII print set. The LP27-U is a fully buffered 
model that operates at a standard speed of up to 1200 lines per minute. 
Forms with up to six parts can be used for multiple copies. A version of the 
LP27 is available for operation of the printer up to 24.5 meters (1000 feet) 
from the host. 
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5.1.4 LA11 DECprinter I 

The LA11 DECprinter I is a medium-speed printer that operates at a standard 
speed of 180 characters per second. It provides a forms length switch to set 
the top of form to any of 11 common lengths, a paper-out switch and alarm, 
and a variable forms width. The LA11 uses a 96-character ASCII set; the 
column width is 132 characters. 


5.1.5 LN01 Laser Page Printer 

The LN01 laser page printer is a nonimpact printer that employs laser 
technology to produce high-quality print. Using electrophotographic imaging 
and xerographic printing, the LN01 prints one page at a time at a rate of 12 
pages per minute. The print resolution of 300 x 300 dots per square inch 
produces characters of even density and alignment. The LN01 uses two, 
188-character, fixed-space fonts; the column width is 132 characters. 


5.1.6 LN03 Laser Page Printer 


The LN03 laser page printer is a table-top, nonimpact page printer that 
uses laser imaging and xerographic printing techniques. The LN03 has a 
printing speed of 8 pages per minute with a print resolution of 300 x 300 dots 
per square inch. Four built-in fonts are available. Several column widths, 
including 80 or 132 characters, are also available. 


5.2 Driver Features 


The line printer drivers provide output character formatting and error 
recovery. These features are described in the following sections. 


5.2.1 Output Character Formatting 

In write virtual and write logical block operations, user-supplied characters 

are output as follows (write physical block data is not formatted, but output 

directly): 

• Rubouts are discarded. 

• Tabs move the horizontal print position to the next MODULO (8) position 
unless the LP$M_TAB characteristic is clear. 

• All lowercase alphabetic characters are converted to uppercase before 
printing (unless the characteristic specifying lowercase characters is set* 
see Section 5.4.3 and Table 5-2). 

• On printers where the line-feed, form-feed, vertical-tab, and carriage- 
return characters empty the printer buffer, returns are held back and 
output only if the next character is not a form feed, line feed, or vertical 
tab. Carriage returns are always output on units that have the LP$M_CR 
characteristic set (see Section 5.4.3 and Table 5-2). 
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• The horizontal print position is incremented on the output of all 
characters, including the space character. Characters are discarded if 

the horizontal print position is equal to or greater than the carriage width, 
unless the LP$M_WRAP characteristic is set or the LP$M_TRUNCATE 
characteristic is clear (see Section 5.3). 

• On printers without a mechanical form feed (the form-feed function 
characteristic is not set; see Section 5.4.3 and Table 5-2), a form feed is 
converted to multiple line feeds. The number of line feeds is based on 
the current line count and the page length. 

• Print lines are counted and returned to the caller in the second longword 
of the I/O status block. 


5.2.2 Error Recovery 

The VMS line printer drivers perform the following error recovery operations: 

• If the printer is off line for 30 seconds, a "device not ready" message is 
sent to the system operator process. 

• If the printer runs out of paper or has a fault condition, a "device not 
ready" message is sent to the system operator after 30 seconds. Successive 
messages, if they occur, are sent 1, 2, 4, 8, . . . minutes after the initial 
message. 

• The current operation is retried every two seconds to test for a changed 
situation, such as the printer coming on line. 

• The current I/O operation can be canceled at the next timeout without 
the printer being on line. 

• When the printer comes on line, device operation resumes automatically. 


5.3 Device Information 

You can obtain information on printer characteristics by using the Get 
Device/Volume Information ($GETDVI) system service. (See the VMS System 
Services Reference Manual.) 

$GETDVI returns line printer characteristics when you specify the item 
codes DVI$_DEVCHAR and DVI$_DEVDEPEND. Tables 5-1 and 
5-2 list these characteristics. The $DEVDEF macro defines the device¬ 
independent characteristics; the $LPDEF macro defines the device-dependent 
characteristics. DVI$_DEVDEPEND returns a longword field that contains 
the device-dependent characteristics in the three low-order bytes and the page 
length in the high-order byte. Maximum page length is 255. 

DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class 
names, which are defined by the $DCDEF macro. The device type is a value 
that corresponds to the printer, for example, LP$__LP27 or LP$_LA11. The 
device class for printers is DC$_LP. DVI$_DEVBUFSIZ returns the page 
width, which is a value in the range of 0 through 255 on a DMF32 controller 
and 0 through 65535 on an LP11 or a DMB32 controller. 


5-3 










Line Printer Driver 

5.3 Device Information 


Table 5—1 Printer Device-Independent Characteristics 


Characteristic 1 

Meaning 

Dynamic Bits (Conditionally Set) 

DEV$M_SPL 

DEV$M_AVL 

Device is spooled. 

Printer is on line and available. 

Static Bits (Always Set) 

DEV$M_REC 

DEV$M_CCL 

DEV$M_ODV 

Device is record-oriented. 

Carriage control is enabled. 

Device is capable of output. 

1 Defined by the $DEVDEF 

macro. 

Table 5-2 Device-Dependent Characteristics for Line Printers 

Value 1 

Meaning 


LP$M_CR 

LP$M_FALLBACK 


Printer requires carriage return. (See Section 5.2.1). 

Printer translates multinational characters to a seven- 
bit equivalent representation if possible. Otherwise, 
an underscore character (_) replaces the character. 
LPM$M_FALLBACK has no effect on physical block 
operations. See Appendix B for a list of multinational 
characters. 


LP$M_LOWER 


LP$M_MECHFORM 


LP$M _PASS ALL 

LP$M-PRINT ALL 

LP$M_TAB 
LP$M_TRUNCATE 


Printer can print lowercase characters. If this value is not 
set, all lowercase characters are converted to uppercase 
when output. (LP$M_LOWER has no effect on write 
physical block operations.) 


Printer has mechanical form feed. This characteristic is 
used when variable form length is required, such as in 
check printing. Driver sends ASCII form feed (decimal 
12). Otherwise, multiple line feeds are generated. The 
page length determines the number of line feeds. 


All output data is in binary (no data interpretation occurs). 
Data termination occurs when the buffer is full (default 
buffer size is 132 bytes). Character formatting is disabled. 

All printing and nonprinting characters are transferred to 
the printer, while character formatting remains enabled. 

Printer enables tab expansion. 

Printer truncates records that are larger than the carriage 
width. 


LP$M_ WRAP 


Printer wraps records that are larger than the carriage 
width. If a string of text is longer than the width specified 
in the second longword, the string is continued on the 
next line. 


1 Defined by the $LPDEF macro. 
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5.4 Line Printer Function Codes 

The basic line printer I/O functions are write, sense mode, and set mode. 
None of the function codes take function modifiers. 


5.4.1 Write 


The line printer write functions print the contents of the user buffer on the 
designated printer. 

The write functions and their QIO function codes are: 

• IO$_WRITEVBLK—Write virtual block 

• IO$_WRITELBLK—Write logical block 

• IO$_WRITEPBLK—Write physical block (the data is not formatted, but 
output directly, as in PASSALL mode on terminals) 

The write function codes can take the following device- or function- 
dependent arguments: 

• pi—The starting virtual address of the buffer that is to be written 

• p2—The number of bytes that are to be written 

• p4_Carriage control specifier except for write physical block operations 

(Write function carriage control is described in Section 5.4.1.1.) 


P3, P5, and P6 are not meaningful for line printer write operations. 


In write virtual block and write logical block operations, the buffer specified 
bv PI and P2 is formatted for the selected line printer and includes the 
carriage control information specified by P4. The default buffer size is 132 
bytes. 

If the printer is not set spooled, write virtual block and write logical block 
operations perform the same function. If the printer is set spooled, a write 
logical block function queues the I/O to the printer, and a write virtual block 
function queues the I/O to the intermediate device, usually a disk. 

All lowercase characters are converted to uppercase if the characteristics of 
the selected printer do not include LP$M_LOWER. (This does not apply to 
write physical block operations.) 


Multiple line feeds are generated for form feeds only if the printer does 
not have a mechanical form feed (LP$M _MECHFORM) characteristic. The 
number of line feeds generated depends on the current page position and the 
page length. 


Section 5.2.1 describes character formatting in greater detail. 
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5.4 Line Printer Function Codes 


5.4.1.1 Write Function Carriage Control 

The P4 argument is a longword that specifies carriage control. Carriage 
control determines the next printing position on the line printer. (P4 is 
ignored in a write physical block operation.) Figure 5-1 shows the P4 
longword format. 


Figure 5-1 P4 Carriage Control Specifier 



3 

2 

1 

0 

P4: 

POSTFIX 

PREFIX 

(not used) 

FORTRAN 


ZK-664-82 


Only bytes 0, 2, and 3 in the longword are used. Byte 1 is ignored. If the 
low-order byte (byte 0) is not 0, the contents of the longword are interpreted 
as a FORTRAN carriage control specifier. Table 5-3 lists the possible byte 0 
values (in hexadecimal) and their meanings. 

If the low-order byte (byte 0) is 0, bytes 2 and 3 of the P4 longword are 
interpreted as the prefix and postfix carriage control specifiers. The prefix 
(byte 2) specifies the carriage control before the buffer contents are printed. 
The postfix (byte 3) specifies the carriage control after the buffer contents are 
printed. The sequence is as follows: 

1 Prefix carriage control 

2 Print 

3 Postfix carriage control 

The prefix and postfix bytes, although interpreted separately, use the same 
encoding scheme. Table 5-4 shows this encoding scheme in hexadecimal 
format. 


Table 5-3 Write Function Carriage Control (FORTRAN: byte 0 not 
equal to 0) 


Byte 0 Value 

(hexadecimal) 

ASCII 

Character 

Meaning 

20 

(space) 

Single-space carriage control (Sequence: 
carriage-return/line-feed combination 1 , print 
buffer contents, return) 

30 

0 

Double-space carriage control (Sequence: 
carriage-return/line-feed combination, 
carriage-return/line-feed combination, print 
buffer contents, return) 

31 

1 A: 

1 

Page eject carriage control (Sequence: form 
feed, print buffer contents, return) 


1 A carriage-return/line-feed combination is a carriage return followed by a line feed. 
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Table 5-3 (Cont.) Write Function Carriage Control (FORTRAN: byte 
0 not equal to 0) 


Byte 0 Value 
(hexadecimal) 


ASCII 

Character 


Meaning 


2B 


24 


All other 
values 


Overprint carriage control; allows double 

printing for emphasis or for special effects 
(Sequence: print buffer contents, return) 

Prompt carriage control (Sequence: carriage- 
return/line-feed combination, print buffer 
contents) 

Same as ASCII space character: single-space 
carriage control 


Table 5-4 Write Function Carriage Control (P4 byte 0 equal to 0) 

Prefix/Postfix Bytes (Hexadecimal) 

Bit 7 

Bits 

0-6 


Meaning 

0 

0 


No carriage control is specified, that 
is, NULL. 

0 

1-7F 


Bits 0 through 6 are a count of 
carriage-return/line-feed combinations. 

Bit 7 

Bit 6 Bit 5 

Bits 0-4 

Meaning 

1 

0 o 

1—IF 

Output the single ASCII control 
character specified by the 
configuration of bits 0 through 4 
(seven-bit character set). 

1 

1 0 

1—IF 

Output the single ASCII control 
character specified by the 
configuration of bits 0 through 

4, which are translated as ASCII 
characters 128 through 159 (eight-bit 
character set; see Appendix B). 


Figure 5-2 shows the prefix and postfix hexadecimal coding that produces 
the carriage control functions listed in Table 5-3. Prefix and postfix coding 
provides an alternative way to achieve these controls. 

In the first example, the prefix/postfix hexadecimal coding for a single-space 
carriage control (carriage-retum/line-feed combination, print buffer contents, 
carriage-return) is obtained by placing the value (1) in the second (prefix) 
byte and the sum of the bit 7 value (80) and the return value (D) in the third 

(postfix) byte: 

80 (bit 7=1) 

+ D (return) 


8D (postfix = return) 
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Figure 5-2 Write Function Carriage Control (Prefix and Postfix 
Coding) 


(Space) 


P4: 

8D 

1 

- 

0 


"0" 

P4: 

8D 

2 

- 

0 


"1" 


P4: 

8D 

8C 

- 

0 



P4: 

8D 

0 

- 

0 




P4: 

0 

1 

- 

0 


Example: Skip 2< 

\ lines before printing 


P4: 

8D 

18 

- 

0 


Sequence: 

Prefix = NL 
Print 

Postfix = CR 


Sequence: 

Prefix = NL, NL 
Print 

Postfix = CR 


Sequence: 

Prefix = FF 
Print 

Postfix = CR 


Sequence: 

Prefix = NULL 
Print 

Postfix = CR 


Sequence: 

Prefix = NL 
Print 

Postfix = NULL 


Sequence: 

Prefix = 24NL 
Print 

Postfix.- CR 


ZK-665-82 


Sense Printer Mode 


The sense printer mode function senses the current device-dependent printer 
characteristics and returns them in the second longword of the I/O status 

IOSSENSEMODE^ function ' de P endent arguments are used with 
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5.4 Line Printer Function Codes 


5.4.3 


Set Mode 


Set mode operations affect the operation and characteristics of the associated 
line printer. The VMS operating system provides two types of set mode 
functions: set mode and set characteristics. Set mode requires logical I/O 
privilege. Set characteristics requires physical I/O privilege. The following 
function codes are provided: 

• IO$_SETMODE 


• IO$_SETCHAR 

These functions take the following device- or function-dependent argument 
(other arguments are not valid): 

pi—The address of a characteristics buffer 

Figure 5-3 shows the quadword PI characteristics buffer for IO$_SETMODE. 
Figure 5-4 shows the same buffer for IO$—SETCHAR. 

Figure 5-3 Set Mode Buffer 


31 ** ^ ,w -, 

page width 

not used 

page length 

printer characteristics 


Figure 5-4 Set Characteristics Buffer 


24 23 16 15 


*** " 

page width 

type 

class 

page length 

printer characteristics 


In the buffer, the device class is DC$_LP. The printer type is a value that 
corresponds to the printer: DT$_LP27 or DT$_LA11. The type can be 
changed by the IO$_SETCHAR function. The page width is a value in the 
range of 0 through 255 on a DMF32 controller and 0 through 65535 on an 
t Pi 1 TYMR39 rnntroller. 


The printer characteristics part of the buffer can contain any of the values 
listed in Table 5-2. 
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5.4 Line Printer Function Codes 


Application programs that change specific line printer characteristics should 
perform the following steps: 

1 Use the IO$_SENSEMODE function to read the current characteristics. 

2 Modify the characteristics. 

3 Use the set mode function to write back the results. 

Failure to follow this sequence will result in clearing any previously set 
characteristic. J 


5.5 I/O Status Block 


The I/O status blocks (IOSB) for the write and set mode I/O functions are 
shown in Figures 5-5 and 5-6. Appendix A lists the status returns for these 
functions. (The VMS System Messages and Recovery Procedures Reference 
Volume provides explanations and suggested user actions for these returns.) 

Figure 5—5 IOSB Contents — Write Function 


31 


16 15 


byte count 


status 


number of lines the paper moved* 


*0 if IO$_WRITEPBLK 


Figure 5—6 IOSB Contents — Set Mode Function 


16 15 



5.6 


Programming Example 

The following sample program (Example 5-1) is an example of I/O to the 
line printer that shows how to use the different carriage control formats. This 
program prints out the contents of the output buffer (OUT—BUFFER) 10 times 
different carriage control formats. The formats are held in location 
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5.6 Programming Example 


Example 5-1 Line Printer Program Example 


• ******************************************************************** 


.TITLE LINE PRINTER PROGRAMMING EXAMPLE 
.IDENT /01/ 


Define necessary symbols. 

$I0DEF ;Define I/O function codes 



; Allocate storage for the necessary data structures. 

; Allocate output buffer and fill with required output text. 

OUT.BUFFER: 

.ASCII "VAX.PRINTER.EXAMPLE" 

OUT_BUFFER_SIZE=.-OUT.BUFFER ;Define size of output string 

; Allocate device name string and descriptor. 


DEVICE.DESCR: 

.LONG 
.LONG 
10$: .ASCII 

20 $: 


20 $- 10 $ 

10 $ 

/LINE.PRINTER/ 


Length of name string 
Address of name string 
Name string of output device 
Reference label to calculate 
length 



; Allocate space to store assigned channel number. 

DEVICE_CHANNEL: * 

3LKW 1 ;Channel number 

; Now set up the carriage control formats. 


0UTPUT_F0RMAT: 

.BYTE 

0,0.0,0 

No carriage control 

.BYTE 

32,0.0.0 

Blank=LF+...TEXT...+CR 

.BYTE 

48,0,0,0 

Zero=LF+LF+...TEXT...+CR 

.BYTE 

49,0,0,0 

One=FF+...TEXT...+CR 

.BYTE 

43,0,0,0 

Plus=Overprint...+CR 

.BYTE 

36,0,0,0 

Dollar=LF+TEXT(Prompt) 


Now set up the prefix-postfix carriage control formats. 



.BYTE 0,0,1,141 
.BYTE 0,0,24,141 
.BYTE 0,0,2,141 
.BYTE 0,0,140,141 


LF+...TEXT...+CR 
24LF+...TEXT...+CR 
LF+LF+...TEXT...+CR 
FF+...TEXT...+CR 


Example 5-1 Cont'd. on next page 
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5.6 Programming Example 



Example 5-1 (Cont.) Line Printer Program Example 


********************************* s|e ****, |c * 3|c , |e **, |ejjcs|c ** + * + + * + + * + + + + + 5|t3|c5|ej)c5|c3je 


Start Program 

************************************************** + ***************** 


The program assigns a channel to the output device, sets up a loop 
count for the number of times it wishes to print, and performs ten 
QIO and wait ($QI0W) system service requests. The channel is then 
deassigned. 


.ENTRY PRINTER_EXAMPLE,~M<R2,R3> ;Program starting address 

First, assign a channel to the output device. 


$ASSIGN_S DEVNAM=DEVICE_DESCR,- 
CHAN=DEVICE_CHANNEL 
BLBC RO,50$ 

MOVL #11,R3 

MOVAL OUTPUT.FORMAT,R2 


Assign a channel to printer 

If low bit = 0, assign failure 
Set up loop count 
Set up o/p format address 
in R2 


Start the printing loop. 


30$: $QI0W_S CHAN=DEVICE_CHANNEL,- 

FUNC=#IO$_WRITEVBLK,- 
P1=0UT_BUFFER,- 
P2=#0UT_BUFFER_SIZE,- 
P4=(R2)+ 

BLBC RO,40$ 

SOBGTR R3,30$ 

40$: $DASSGN_S CHAN=DEVICE_CHANNEL 

50$: RET 

.END PRINTER.EXAMPLE 


;Print on device channel 


;I/0 function is write virtual 
;Address of output buffer 
;Size of buffer to print 
;Format control in R2 
;will autoincrement 
;If low bit = 0, I/O failure 
;Branch if not finished 
;Deassign channel 
;Return 
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0 Magnetic Tape Drivers 





This chapter describes the use of the VMS magnetic tape drivers. These 
drivers support the devices listed in Table 6-1. 


Table 6-1 Supported Magnetic Tape Devices 







Tape 

Max. Data Transfer 





No. of 

Recording 

Speed 

Rate (bytes 

Recording Method- 


Drive 1 



Density (bpi) 

(ips) 

per second) 

TS11 

TS04 

MS 

9 

1600 

45 

72,000 

PE 

TM03 

TE16 

MT 

9 

800 or 1600 

45 

36,000 (for 800 
bpi); 72,000 (for 

1600 bpi) 

NRZI or PE 


TU45 

MT 

9 

800 or 1600 

75 

60,000 (for 800 
bpi); 120,000 (for 

1600 bpi) 

NRZI or PE 


TU77 

MT 

9 

800 or 1600 

125 

100,000 (for 800 
bpi); 200,000 (for 

1600 bpi) 

NRZI or PE 

TM78 

TU78 

MF 

9 

1600 or 6250 

125 

200,000 (for 1600 
bpi): 781,250 (for 

6250 bpi) 

PE or GCR 

3 

TU80 

MS 

9 

1600 

25 or 
100 

160,000 

PE 

3 

TU81 

MU 

9 

1600 or 6250 

25 or 

120,000 (for 1600 

PE or GCR 


TU81 



75 

bpi); 468,750 (for 



-Plus 





6250 bpi) 



TQ81 







HSC50 

TA81 

MU 

9 

1600 or 6250 

25 or 
75 

120,000 (for 1600 
bpi); 468,750 (for 

6250 bpi) 

PE or GCR 


TA78 

MF 

9 

1600 or 6250 

125 

200,000 (for 1600 
bpi); 781,250 (for 

6250 bpi) 

PE or GCR 




TA79 

MU 

9 

1600 or 6250 

125 

769,000 

PE or GCR 

TUK50 

TQK50 

TZK50 

TK50 5 

MU 

22 4 

6666 

75 

45,000 

MFM 

LESI 

RV20 

MU 

9 

6250 

N/A 

1.33 Megabytes 

Write once 
optical disk 


Adapter 


ijhe TU81, TU81-Plus. TA78, TU78. TA81, and TF30 are tape mass storage control protocol (TMSCP) drives. The 

TZ30 is an SCSI drive. 

2 N rzI = non-return-to-zero-inverted; PE = phase encoded; GCR - group-coded recording; MFM = modified frequency 
modulation; HDMFM = high density modified frequency modulation 


3 Has a self-contained controller 

4 Each track written separately—not in parallel 

5 The TK50 is a tape mass storage control protocol (TMSCP) device when configured on( . . IBA23 1 BA1 23^w/s) 
systems. The TK50 has a self-contained controller when configured on VAXstation 2000 and MicroVA 

systems. 
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Table 6-1 (Cont.) Supported Magnetic Tape Devices 


Controller 

3- 


1 No. of Recording 

Drive Code Tracks Density (bpi) 

TF30 MU 22 4 6666 

TZ30 


Tape Max. Data Transfer 

Speed Rate (bytes 

(ips) per second) 

75 45,000 


Recording Method 2 

MFM 


TQK70 TK70 MU 48 10000 100 

™ 79 TU79 MF 9 1600 or 6250 125 

'The TU81, TU81-Plus, TA78, TU78, TA81, and TF30 

TZ30 is an SCSI drive. 


90,000 HDMFM 

769,000 pe or GCR 

are tape mass storage control protocol (TMSCP) drives. The 


2 NRZI - non-return-to-zero-inverted; PE = phase encoded; GCR = group-coded recording; 
modulation; HDMFM - high density modified frequency modulation 

3 Has a self-contained controller 

4 Each track written separately—not in parallel 


MFM = modified frequency 


Supported Magnetic Tape Controllers 

The following sections describe the VMS magnetic tape controllers. 


TM03 Magnetic Tape Controller 


The TM03 magnetic tape controller supports up to eight TE16, TU45 or TU77 
!E?Pe drives These dual-density (800 or 1600 bpi) drives differ in speed: the 
TE16, TU45, and TU77 read and write data at 45, 75, and 125 inches per 
second, respectively. Each drive can hold one 2400-foot, 9-track reel with 
a capacity of approximately 40 million characters. The TM03 controller is 
connected to the MASSBUS through a MASSBUS adapter. 


TS11 Magnetic Tape Controller 

magnetic ta P e controller connects to the UNIBUS through a 
UNIBUS adapter and supports one TS04 tape drive. The TS11/TS04 is a 
single-density tape system that supports 1600-bpi, phase-encoded recording. 

TM78 Magnetic Tape Controller 


The TM78 magnetic tape controller supports up to four TU78 tape drives 
These high-performance, dual-density drives (1600 or 6250 bpi) operate at 
25 inches per second (ips) using a 2400-foot reel of tape with a capacity 
of approximately 146 million characters when recorded in the GCR (6250 

xFl T J he ™ 78 contr °H er is connected to the MASSBUS through a 

MASSBUS adapter. ° 
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6.1 Supported Magnetic Tape Controllers 


6.1.4 TU80 Magnetic Tape Subsystem 

The TU80 is a single-density, dual-speed (25 or 100 ips) magnetic tape 
subsystem that uses streaming tape technology (see Section 6.2.4). It supports 
one drive per subsystem. The TU80 connects to the UNIBUS through a 
UNIBUS adapter and completely emulates the TS11 magnetic tape controller. 


6.1.5 TU81 and TA81 Magnetic Tape Subsystems 

The TU81 and the TA81 are high-performanace, dual-density (1600 or 6250 
bpi), dual-speed (25 or 75 ips) magnetic tape subsystems that use streaming 
tape technology (see Section 6.2.4). The TU81 connects to the UNIBUS 
through a UNIBUS adapter. The TA81 attaches to an HSC50 controller. Both 
drives are managed with the tape mass storage control protocol (TMSCP). 


6.1.6 TK50 Cartridge Tape System 

The TK50 is a 5.24-inch, 95-megabyte cartridge tape that uses streaming 
tape technology (see Section 6.2.4). The TK50 records data serially on 22 
tracks using serpentine recording, rather than on separate (parallel) tracks. 
Data written to tape is automatically read as it is written. A CRC check is 
performed and the controller is notified immediately if an error occurs on 
the tape The TQK50 is a dual-height Q-BUS controller for the TK50 tape 
drive The TUK50 is a UNIBUS controller for the same drive. Both the 
TQK50 and the TUK50 are TMSCP devices. The TZK50 is not a TMSCP 
device; it contains its own internal controller. Only one drive is supported per 
controller. 


6.2 Driver Features 

The VMS magnetic tape drivers provide the following features: 

• Multiple master adapters and slave formatters 

• Different types of devices on a single MASSBUS adapter; for example, an 
RP05 disk and a TM03 tape formatter 

• Reverse read function (except for the TK50 on TUK50 and TQK50 
controllers) 

• Reverse data check function (except for TS11, and TK50 on TUK50 and 
TQK50 controllers) 

• Data checks on a per-request, per-file, or per-volume basis (except for 
TS11) 

• Full recovery from power failure for online drives with volumes mounted, 
including repositioning by the driver (except on VAXstation 2000 and 
Micro VAX 2000 systems) 

• Extensive error recovery algorithms; for example, non-retum-to-zero- 
inverted (NRZI) error correction 

• Logging of device errors in a file that may be displayed by field service or 
customer personnel 

• Online diagnostic support for drive level diagnostics 
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6.2 Driver Features 



The following sections describe master and slave controllers, and data check 
and error recovery capabilities in greater detail. 


6.2.1 Master Adapters and Slave Formatters 

The VMS operating system supports the use of many master adapters of the 
same type on a system. For example, more than one MASSBUS adapter 
(MBA) can be used on the same system. A master adapter is a device 
controller capable of performing and synchronizing data transfers between 
memory and one or more slave formatters. 

The VMS operating system also supports the use of multiple slave formatters 
per master adapter on a system. For example, more than one TM03 or TM78 
magnetic tape formatter per MBA can be used on a system. A slave formatter 
accepts data and commands from a master adapter and directs the operation 
of one or more slave drives. The TM03 and the TM78 are slave formatters. 
The TE16, TU45, TU77, and TU78 magnetic tape drives are slave drives. 



6.2.2 Data Check 


After successful completion of an I/O operation, a data check is made to 
compare the data in memory with that on the tape. After a write or read 
(forward) operation, the tape drive spaces backward, and then performs a 
write check data operation. After a read operation in the reverse direction, 
the tape drive spaces forward, and then performs a write check data reverse 
operation. With the exception of TS04 and TU80 drives, magnetic tape 
drivers support data checks at the following three levels: 


• Per request You can specify the data check function modifier 

(IO$M_DATACHECK) on a read logical block, write logical block, read 
virtual block, write virtual block, read physical block, or write physical 
block I/O function. 






Per volume—You can specify the characteristics "data check all reads" 
and "data check all writes" when the volume is mounted. The VMS DCL 
Dictionary describes volume mounting and dismounting. The VMS System 
Services Reference Manual describes the Mount Volume ($MOUNT) and 
Dismount Volume ($DISMOU) system services. 


Per file—You can specify the file attributes "data check on read" or 
"data check on write." File access attributes are specified when the file 
is accessed. Chapter 1 of this manual and the VMS Record Management 
Services Manual both describe file access. 


Data check is distinguished from a BACKUP/VERIFY operation, which writes 
an entire save set, rewinds, and then compares the tape to the original tape. 

See Section 6.1.6 for information on TK50 data check. 


Note: Read and write operations with data check can result in very slow 
performance on streaming tape drives. 
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6.2 Driver Features 


6.2.3 Error Recovery 

Error recovery in the VMS operating system is aimed at performing all 
possible operations that enable an I/O operation to complete successfully. 
Magnetic tape error recovery operations fall into the following two categories: 


• Handling special conditions, such as power failure and interrupt timeout 

• Retrying nonfatal controller or drive errors 

The error recovery algorithm uses a combination of these types of error 
recovery operations to complete an I/O operation. 

Power failure recovery consists of repositioning the reel to the position held at 
the start of the I/O operation in progress at the time of the power failure, and 
then reexecuting this operation. This repositioning might or might not require 
operator intervention to reload the drives. When such operator intervention 
is required, "device not ready" messages are sent to the operator console to 
solicit reloading of mounted drives. Power failure recovery is not supported 
on VAXstation 2000 and MicroVAX 2000 systems. 

Device timeout is treated as a fatal error, with a loss of tape position. A tape 
on which a timeout has occurred must be dismounted and rewound before 
the drive position can be established. 

If a nonfatal controller/drive error occurs, the driver (or the controller, 
depending on the type of drive) attempts to reexecute the I/O operation up 
to 16 times before returning a fatal error. The driver repositions the tape 
before each retry. 

The inhibit retry function modifier (IO$M_INHRETRY) inhibits all normal 
(nonspecial conditions) error recovery. If an error occurs, and the request 
includes that modifier, the operation is immediately terminated and the driver 
returns a failure status. IO$M_INHRETRY has no effect on power failure and 
timeout recovery. 

The driver can write up to 16 extended interrecord gaps during the error 
recovery for a write operation. For the TE16, TU45, and TU77, writing these 
gaps can be suppressed by specifying the inhibit extended interrecord gap 
function modifier (IO$M_INHEXTGAP). This modifier is ignored for the 
other magnetic tape drives. 


6.2.4 Streaming Tape Systems 

Streaming tape systems (TU80, TU81, TU81-Plus, TA81, TK50, TK70, TF30, 
and TZ30) use the supply and takeup reel mechanisms to control tape speed 
and tension directly, thereby eliminating the need for more complex and 
costly tension and drive components. Streaming tapes have a very simple 
tape path, much like a home audio reel-to-reel recorder. 

Note: Read and write operations with data check can result in very slow 
performance on streaming tape drives. 

Because the motors driving the reels are low-powered, and because there is no 
tape buffering, streaming tape drives are not capable of starting and stopping 
in the interrecord gaps like conventional tape drives. When a streaming tape 
does have to stop, the following events occur: 

1 The tape slowly coasts forward to a stop. 
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2 It backs up over a section previously processed. 

3 It halts to await the next command. 

4 It accelerates so that, when the original interrecord gap is encountered, 
the tape is moving at full speed. 

These steps, allowing the tape to reposition, require approximately one- 
half second to complete on TU8x tapes and about three seconds on TK50 
tapes. If the operating system is not capable of writing to, or reading from, 
a streaming tape drive at a rate that will keep the drive in constant motion 
(streaming) the drive repositions itself when it runs out of commands to 
execute. That produces a situation known as thrashing, in which the relatively 
long reposition times exceed the time spent processing data and the result is 
lower-than-expected data throughput. 

Thrashing is entirely dependent on how fast the system can process data 
relative to the tape drive speed while streaming. Consequently, the greatest 
efficiency is obtained when you provide sufficient buffering to ensure 
continuous tape motion. Some streaming tape drives supported by the 
VMS operating system (TU80, TU81, TU81-Plus, and TA81) are dual-speed 
devices that automatically adjust the tape speed to maximize data throughput 
and minimize thrashing. 

The TK50 writes up to seven filler records to keep the tape in motion. These 
records are ignored when the data is read. 


6.3 Device Information 

You can obtain information on all magnetic tape device characteristics by 
using the Get Device/Volume Information ($GETDVI) system service. (See 
the VMS System Services Reference Manual.) 

$GETDVI returns magnetic tape characteristics when you specify the item 
codes DVI$_DEVCHAR, DVI$_DEVCHAR2, DVI$_DEVDEPEND, and 
DVI$_DEVDEPEND2. Tables 6-2, 6-3, and 6-4 list these characteristics. The 
$DEVDEF macro defines the device-independent characteristics, the $MTDEF 
macro defines the device-dependent characteristics, and the $MT2DEF 
macro defines the extended device characteristics. The extended device 
characteristics apply only to the TU81-Plus. 


Table 6-2 Magnetic Tape Device-Independent Characteristics 


Characteristic 1 

Meaning 

Dynamic Bits (Conditionally Set) 

DEV$M_AVL 

Device is online and available. 

DEV$M_FOR 

Volume is foreign. 

DEV$M_MNT 

Volume is mounted. 

DEV$M_RCK 

Perform data check on all read operations. 

DEV$M_WCK 

Perform data check on all write operations. 


'Defined by the $DEVDEF macro. 
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6.3 Device Information 

Magnetic Tape Device-Independent 

Characteristics 

Characteristic 1 

Meaning 

Static Bits (Always Set) 

DEV$M_FOD 

DEV$M_IDV 

DEV$M_ODV 

DEV$M_SQD 

DEV$M_WBC 2 

Device is file-oriented. 

Device is capable of input. 

Device is capable of output. 

Device is capable of sequential access. 

Device is capable of write-back caching. 


defined by the $DEVDEF macro. 

2 This bit is located in DVI$_DEVCHAR2 


Table 6-3 Device-Dependent Information for Tape Devices 


Characteristic 1 

Meaning 

MT$M_LOST 

MT$M_HWL 

MT$M_EOT 

If set, the current tape position is unknown. 

If set, the selected drive is hardware write-locked. 

If set, an end-of-tape (EOT) condition was encountered 
by the last operation to move the tape in the forward 
direction. 

MT$M_EOF 

If set, a tape mark was encountered by the last operation 
to move tape. 

MT$M_BOT 

If set, a beginning-of-tape (BOT) marker was encountered 
by the last operation to move tape in the reverse 
direction. 

MT$M_PARITY 

If set, all data transfers are performed with even parity. If 
clear (normal case), all data transfers are performed with 
odd parity. Only non-return-to-zero-inverted recording at 
800 bpi can have even parity. 

MT$V_DENSITY 

MT$S_DENSITY 

Specifies the density at which all data transfer operations 
are performed. Possible density values are as follows: 
MT$K_GCR_6250 Group-coded recording, 6250 bpi 

MT$K_PE_1600 Phase-encoded recording, 1600 bpi 

MT$K_NRZI_800 Non-return-to-zero-inverted 

recording, 800 bpi 

MT$K_BLK_833 Cartridge block mode recording 2 

MT$V_FORMAT 

MT$S_FORMAT 

Specifies the format in which all data transfers are 
performed. A possible format value is as follows: 
MT$K_NORMAL11 Normal PDP-11 format. Data bytes 
are recorded sequentially on tape 
with each byte occupying exactly 
one frame. 


1 Defined by the $MTDEF macro. 
2 Only for the TK50, TF30, and TZ30 
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Table 6—4 Extended Device Characteristics for Tape Devices 

Characteristic 1 

Meaning 

MT2$V_WBC_ENABLE 

MT2$V_RDC_DISABLE 

If set, write-back caching is enabled for this unit. 

If set, read caching is disabled for this unit. 


1 Defined by the $MT2DEF macro. Only for the TU81-Plus. Initial device status will 
show both of these bits cleared; write-back caching will be disabled, read caching will be 
enabled. 


DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class 
names, which are defined by the $DCDEF macro. DVI$_DEVBUFSIZ returns 
the buffer size. The buffer size is the default to be used for tape transfers 
(normally 2048 bytes). The device class for magnetic tapes is $DCTAPE, and 
the device type is determined by the magnetic tape model. For example, the 
device type for the TA78 is DT$_TA78, for the TA81 it is DT$_TA81. 


6.4 Magnetic Tape Function Codes 

The VMS magnetic tape driver can perform logical, virtual, and physical 
I/O functions. Foreign-mounted devices do not require privilege to perform 
logical and virtual I/O requests. 

Logical and physical I/O functions to magnetic tape devices allow sequential 
access to volume storage and require only that the requesting process have 
direct access to the device. The results of logical and physical I/O operations 
are unpredictable if an ACP is present. 

Virtual I/O functions require intervention by an ACP and must be executed 
in a prescribed order. The normal order is to create and access a file, write 
information to that file, and deaccess the file. Subsequently, when you access 
the file, you read the information and then deaccess the file. You can write 
over the file when the information it contains is no longer useful and the file 
has expired. 

Any number of bytes (from a minimum of 14 to a maximum of 65,535) can 
be read from or written into a single block by a single request. The number 
of bytes itself has no effect on the applicable quotas (direct I/O, buffered I/O, 
and AST). Reading or writing any number of bytes subtracts the same amount 
from a quota. 

The volume to which a logical or virtual function is directed must be mounted 
for the function actually to be executed. If it is not, either a "device not 
mounted" or "invalid volume" status is returned in the I/O status block. 

Table 6-5 lists the logical, virtual, and physical magnetic tape I/O functions 
and their function codes. These functions are described in more detail in 
the following paragraphs. Chapter 1 describes the QIO level interface to the 
magnetic tape device ACP. 
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Table 6-5 Magnetic Tape I/O Functions 


Function Code and 
Arguments 

Type 1 

Function Modifiers 

Function 

IO$_CREATE P1,- 
[P2[,[P3],[P4],- 

V 

IO$M_CREATE 

IO$M-ACCESS 

Create a file. 

[P5] 

IO$_ACCESS PI,- 

V 

IO$M -CREATE 

Search a tape for a specified file and 

P2],[P3],[P4],- 

[P5] 


IO$M-ACCESS 

access the file if found and 

IO$M_ACCESS is set. If the file is not 
found and IO$M_CREATE is set, create a 
file at end-of-tape (EOT) marker. 

IO$_DEACCESS P1,- 
[P2],[P3],[P4],- 

V 


Deaccess a file and, if the file has been 
written, write out trailer records. 

[P5] 

IO$_DSE 2 

p 

IO$M_NOWAIT 

Erase a prescribed section of the tape. 

IO$_MODIFY PI,- 

V 


Write user labels. 

[P2],[P3],[P4] ( - 

[P5] 

IO$_READVBLK P1,P2 

V 

IO$M_DAT ACHECK 3 
IO$M_INHRETRY 
IO$M_REVERSE 4 

Read virtual block. 

IO$_READLBLK P1,P2 

L 

IO$M-DAT ACHECK 3 
IO$M_INHRETRY 

IO$M-REVERSE 4 

Read logical block. 

IO$_READPBLK P1,P2 

P 

IO$M_DAT ACHECK 3 
IO$M_INHRETRY 

IO$M-REVERSE 4 

Read physical block. 

IO$_WRITEVBLK P1,P2 

V 

IO$M-DAT ACHECK 3 
IO$M_INHRETRY 
IO$M_INHEXTGAP 7 
IO$M_NOWAIT 5 

Write virtual block. 

IO$_WRITELBLK P1,P2 

L 

IO$M_ERASE 6 

IO$M_DAT ACHECK 3 
IO$M -INHRETRY 
IO$M_INHEXTGAP 7 
IO$M_NOWAIT 5 

Write logical block. 

IO$_WRITEPBLK P1,P2 

P 

IO$M_ERASE 6 

IO$M _D AT ACHECK 3 
IO$M_INHRETRY 

IO$M-INHEXTGAP 7 
IO$M_NOWAIT 5 

Write physical block. 


’V - virtual; L = logical; P = physical 


2 Only for TMSCP drives, TZK50, and TZ30 
3 Not for TS04 and TU80 
4 Not for TUK50 and TQK50 
5 Only for TU81-Plus drives 

6 Takes no arguments; valid only for TMSCP drives, TZK50, and TZ30 
7 0nly for TE16, TU45, and TU77 
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Table 6-5 (Cont.) Magnetic Tape I/O Functions 


Function Code and 
Arguments 

Type 1 

Function Modifiers 

Function 

I0$_REWIND 

L 

IO$M_INHRETRY 

IO$M_NOWAIT 

Reposition tape to the beginning-of-tape 
(BOT) marker. 

I0$_REWIND0FF 

L 

IO$M_INHRETRY 

I0$M_N0WAIT 

Rewind and unload the tape on the 
selected drive. 

I0$_UNL0AD 

L 

IO$M_INHRETRY 

IO$M_NOWAIT 

Rewind and unload the tape on the 
selected drive. 

IO$_SKIPFILE PI 

L 

IO$M_INHRETRY 

IO$M_NOWAIT 5 

Skip past a specified number of tape 
marks in either a forward or reverse 
direction. 

IO$_SKIPRECORD PI 

L 

IO$M_INHRETRY 

I0$M_N0WAIT 5 

Skip past a specified number of blocks in 
either a forward or reverse direction. 

IO$_WRITEOF 

L 

I0$M_INHRETRY 

IO$M_INHEXTGAP 7 

I0$M_N0WAIT 5 

Write an extended interrecord gap 
followed by a tape mark. 

IO$_PACKACK 

P 


Initialize volume valid bit. 

IO$_AVAILABLE 

P 


Clear volume valid bit. 

IO$_SENSEMODE [P1]- 
[P2] 8 

L 

IO$M_INHRETRY 

Sense the tape characteristics and return 
them in the I/O status block. 

IO$_SENSECHAR [P1]- 
[P2] 8 

P 

IO$M_INHRETRY 

Sense the tape characteristics and return 
them in the I/O status block. 

I0$_SETM0DE P1,- 
[P2] 8 

L 


Set tape characteristics for subsequent 
operations. 

IO$_SETCHAR P1,- 
[P2] 8 

P 


Set tape characteristics for subsequent 
operations. 

IO$_ACPCONTROL P1,- 

[P2],[P3],[P4],- 

[P5] 

V 

IO$M_DMOUNT 

Perform miscellaneous control functions. 9 

1 V = virtual; L = logical; P = 
5 Only for TU81-Plus drives 

physical 



7 Only for TE16, TU45, and TU77 



8 The PI and P2 arguments for IO$_SENSEMODE and IO$_SENSECHAR and the P2 argument for IO$_SETMODE and 
IO$_SETCHAR are for TMSCP drives only 

9 See Section 1.6.7 for additional information. 



The function-dependent arguments for IO$__CREATE, IO$__ACCESS, 

IO$_DEACCESS, IO$_MODIFY, IO$_ACPCONTROL are as follows: 

• PI—The address of the file information block (FIB) descriptor. 

• P2—Optional. The address of the file name string descriptor. If specified 
with IO$_ACCESS, the name identifies the file being sought. If specified 
with IO$_CREATE, the name is the name of the created file. 

• P3—Optional. The address of the word that is to receive the length of 
the resultant file name string. 
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• P4—Optional. The address of a descriptor for a buffer that is to receive 
the resultant file name string. 

• ps—Optional. The address of a list of attribute descriptors. If specified 
with IO$_ACCESS, the attributes of the file are returned to the user. If 
specified with IO$_CREATE, P5 is the address of the attribute descriptor 
list for the new file. All file attributes for IO$_MODIFY are ignored. 

See Chapter 1 for more information on these functions. 

The function-dependent arguments for IO$_READVBLK, IO$_READLBLK, 

IO$_READPBLK, IO$_WRITEVBLK, IO$_WRITELBLK, and IO$_ 

WRITEPBLK are as follows: 

• pi—The starting virtual address of the buffer that is to receive the data 
in the case of a read operation; or, in the case of a write operation, the 
virtual address of the buffer that is to be written on the tape. 

• P2—The length of the buffer specified by PI 

The function-dependent argument for IO$_SKIPFILE and IO$_SKIPRECORD 

is: 

• PI—The number of tape marks to skip over in the case of a skip file 
operation; or, in the case of a skip record operation, the number of blocks 
to skip over. If a positive number is specified, the tape moves forward; if 
a negative number is specified, the tape moves in reverse. (The maximum 
number of tape marks or records that PI can specify is 32,767.) 

The following example shows the correct method of defining the PI 

parameter in a IO$_SKIPRECORD QIO. 




TAPE.CHAN: 



.WORD 

0 

IOSB: 

.WORD 

0 


.WORD 

0 


.LONG 

0 

DEVICE: 

.ASCID 

/$127$MUA0:/ 

RECORD: 

.LONG 

2000 


.PSECT 

CODE,EXE,NOWRT 

: 

.ENTRY 

MT_I0,~M<> 


$ASSIGN_S CHAN=TAPE_CHAN,- 

DEVNAM=DEVICE 


BLBC 

R0,EXIT_ERR0R 


$QI0W_S 

CHAN=TAPE_CHAN,- 
FUNC=#I0$_SKIPREC0RD 
I0SB=I0SB,- 
P1=REC0RD 


BLBC 

R0,EXIT_ERR0R 


$EXIT_S 

R0 


EXIT.ERROR: 


$EXIT_S 

R0 

.END 

MT. 
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Read 


The read function reads data into a specified buffer in the forward or reverse 
direction starting at the next block position. 

The VMS operating system provides the following read function codes: 

• IO$_READVBLK—Read virtual block 

• IO$_READLBLK—Read logical block 

• IO$_READPBLK—Read physical block 

If a read virtual block function is directed to a volume that is mounted 
foreign, it is converted to a read logical block function. If a read virtual block 
function is directed to a volume that is mounted structured, the volume is 
handled the same way as a file-structured device. 

Two function-dependent arguments are used with these codes: PI and P2. 
These arguments are described in Section 6.4. 

If the read function code includes the reverse function modifier 
(IO$M—REVERSE), the drive reads the tape in the reverse direction instead 
of the forward direction. IO$M_REVERSE cannot be specified for the TUK50 
and TQK50 devices. 

The data check function modifier (IO$M__DATACHECK) can be used with 
all read functions. If this modifier is specified, a data check operation is 
performed after the read operation completes. (The drive performs a space 
reverse or space forward between the read and data check operations.) A data 
check operation is also performed if the volume that was read, or the volume 
on which the file resides (virtual read), has the characteristic "data check all 
reads." Furthermore, a data check is performed after a virtual read if the file 
has the attribute "data check on read." The TS04 and TU80 tape drives do not 
support the data check function. 

For read physical block and read logical block functions, the drive returns 
the status SS$_NORMAL (not end-of-tape status) if either of the following 
conditions occurs and no other error condition exists: 

• The tape is positioned past the end-of-tape (EOT) position at the start of 
the read (forward or reverse) operation. 

• The tape enters the EOT region as a result of the read (forward) operation. 

The transferred byte count reflects the actual number of bytes read. 

If the drive reads a tape mark during a logical or physical read operation in 
either the forward or reverse direction, any of the following conditions can 
return an end-of-file status: 

• The tape is positioned past the EOT position at the start of the read 
operation. 

• The tape enters the EOT region as a result of the read operation. 

• The drive reads a tape mark as a result of a read operation but the tape 
does not enter the EOT region. 
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An end-of-file status is also returned if the drive attempts a read operation 
in the reverse direction when the tape is positioned at the beginning-of-tape 
(BOT) marker. All conditions that cause an end-of-file status result in a 
transferred byte count of zero. 

If the drive attempts to read a block that is larger than the specified memory 
buffer during a logical or physical read operation, a data overrun status is 
returned. The buffer receives only the first part of the block. On a read in the 
reverse direction (on drives other than the TK50 and TZ30) the buffer receives 
only the latter part of the block. The transferred byte count is equal to the 
actual size of the block. Read reverse starts at the top of the buffer. Thus, 
the start of the block is at PI plus P2 minus the length read. The TUK50 and 
TZ30 cannot actually perform read reverse operations; they must be simulated 
by the driver. Therefore, the data returned are those that would have been 
returned had the block been read in the forward direction. 

It is not possible to read a block that is less than 14 bytes in length. Records 
that contain less than 14 bytes are termed "noise blocks" and are completely 
ignored by the driver. 


6.4.2 Write 

The write function writes data from a specified buffer to tape in the forward 
direction starting at the next block position. 

The VMS operating system provides the following write function codes: 

• IO$_WRITEVBLK—Write virtual block 

• IO$_WRITELBLK—Write logical block 

• IO$_WRITEPBLK—Write physical block 

If a write virtual block function is directed to a volume that is mounted 
foreign, the function is converted to a write logical block. If a write virtual 
block function is directed to a volume that is mounted structured, the volume 
is handled the same way as a file-structured device. 

Two function-dependent arguments are used with these codes: PI and P2. 
These arguments are described in Section 6.4. 

The IO$M_ERASE function modifier can be used with the IO$_WRITELBLK 
and IO$_WRITEPBLK function codes to erase a user-selected part of a tape. 
This modifier propagates an erase pattern of all zeros from the current tape 
position to 10 feet past the EOT position and then rewinds to the BOT 
marker. 

The data check function modifier (IO$M_DATACHECK) can be used with 
all write functions. If this modifier is specified, a data check operation is 
performed after the write operation completes. (The drive performs a space 
reverse between the write and the data check operations.) The driver forces 
a data check operation when an error occurs during a write operation. This 
ensures that the data can be reread. A data check operation is also performed 
if the volume written, or the volume on which the file resides (virtual write), 
has the characteristic "data check all writes." Furthermore, a data check 
is performed after a virtual write if the file has the attribute "data check 
on write." The TS04 and TU80 tape drives do not support the data check 
function. 
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If the IO$M_NOWAIT function modifier is specified, write-back caching is 
enabled on a per command basis. IO$M_NOWAIT is applicable only to 
TU81-Plus drives. 

If the drive performs a write physical block or a write logical block operation, 
an EOT status is returned if either of the following conditions occurs and no 
other error condition exists: 

• The tape is positioned past the EOT position at the start of the write 
operation. 

• The tape enters the EOT region as a result of the write operation. 

The transferred byte count reflects the size of the block written. It is not 
possible to write a block less than 14 bytes in length. An attempt to do so 
results in the return of a bad parameter status for the QIO request. 


6.4.3 Rewind 

The rewind function repositions the tape to the beginning-of-tape (BOT) 
marker. If the IO$M_NOWAIT function modifier is specified, the I/O 
operation is completed when the rewind is initiated. Otherwise, I/O 
completion does not occur until the tape is positioned at the BOT marker. 
IO$_REWIND has no function-dependent arguments. 


6.4.4 Skip File 


The skip file function skips past a specified number of tape marks in either a 
forward or reverse direction. A function-dependent argument (PI) is provided 
to specify the number of tape marks to be skipped, as shown in Figure 6-1. 

If a positive file count is specified, the tape moves forward; if a negative file 
count is specified, the tape moves in reverse. (The actual number of files 
skipped is returned as a signed number in the I/O status block.) 

Figure 6-1 IO$_SKIPFILE Argument 


PI: 


31 


16 15 


0 


not used 


file count 


ZK-671-82 


Only tape marks (when the tape moves in either direction) and the BOT 
marker (when the tape moves in reverse) are counted during a skip file 
operation. The BOT marker terminates a skip file function in the reverse 
direction. The end-of-tape (EOT) marker does not terminate a skip file 
function in either the forward or reverse direction. A negative skip file 
function leaves the tape positioned just before a tape mark (at the end of 
a file) unless the BOT marker is encountered, whereas a positive skip file 
function leaves the tape positioned just past the tape mark. 

A skip file function in the forward direction can also be terminated if two 
consecutive tape marks are encountered. Section 6.4.5.1 describes this feature. 
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6.4.5 Skip Record 

The skip record function skips past a specified number of physical tape blocks 
in either a forward or reverse direction. A device- or function-dependent 
argument (PI) specifies the number of blocks to skip, as shown in Figure 6-2. 
If a positive block count is specified, the tape moves forward; if a negative 
block count is specified, the tape moves in reverse. The actual number of 
blocks skipped is returned as a signed number in the I/O status block. If 
a tape mark is detected, the count is the number of blocks skipped, plus 1 
(forward tape motion) or minus 1 (reverse tape motion). 


Figure 6-2 IO$_SKIPRECORD Argument 



31 


16 

15 


0 

PI: 

not used 

block count 







ZK-672-82 


A skip record operation is terminated by the end-of-file marker when the 
tape moves in either direction, by the BOT marker when the tape moves in 
reverse, and by the EOT marker when the tape moves forward. 


A skip record function in the forward direction can also be terminated if 
the tape was originally positioned between two tape marks. Section 6.4.5.1 
describes this feature. 


6.4.5.1 Logical End-of-Volume Detection 

A skip file or skip record operation is terminated when both of the following 
conditions exist: 

• The tape is mounted foreign. 

• Two consecutive tape marks are encountered when the tape moves in the 
forward direction. 

After the operation terminates, the tape remains positioned between the two 
tape marks that were detected. The I/O status block (IOSB) returns the status 
SS$_ENDOFVOLUME and the actual number of files (or records) skipped 
during the operation prior to the detection of the second tape mark. The skip 
count is returned in the high-order word of the first longword of the IOSB. 

Subsequent skip record (or skip file) requests terminate immediately when 
the tape is positioned between the two tape marks, producing no net tape 
movement and returning the SS$_ENDOFVOLUME status with a skip count 
of zero. 

To move the tape beyond the second tape mark, you must employ another 
I/O function. For example, the IO$_READLBLK function, if issued after 
receipt of the SS$_ENDOFVOLUME status return, terminates with an 
SS$_ENDOFFILE status and with the tape positioned just past the second 
tape mark. From this new position, other skip functions could be issued to 
produce forward tape motion (assuming there is additional data on the tape). 
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If three consecutive tape marks are encountered during a skip file function, 
you must issue two IO$_READLBLK functions, the first to get the 
SS$_ENDOFFILE return, the second to position the tape past the third tape 
mark. 


6.4.6 Write End-of-File 

The write-end-of-file function writes an extended interrecord gap (of 
approximately 3 inches for non-retum-to-zero-inverted (NRZI) recording 
and 1.5 inches for phase-encoded (PE) recording) followed by a tape mark. 
No device- or function-dependent arguments are used with IO$_WRITEOF. 

An end-of-tape (EOT) status is returned in the I/O status block if either of 
the following conditions is present and no other error conditions occur: 

• A write end-of-file function is executed while the tape is positioned past 
the EOT marker. 

• A write end-of-file function causes the tape position to enter the EOT 
region. 


6.4.7 Rewind Offline 


The rewind offline function rewinds and unloads the tape on the selected 
drive. If the IO$M__NOWAIT function modifier is specified, the I/O operation 
is completed as soon as the rewind operation is initiated. No device- or 
function-dependent arguments are used with IO$_REWINDOFF. 


6.4.8 Unload 


The unload function rewinds and unloads the tape on the selected drive. 
The unload function is functionally the same as the rewind offline function. 
If the IO$M_NOWAIT function modifier is specified, the I/O operation 
is completed as soon as the rewind operation is initiated. No device- or 
function-dependent arguments are used with IO$_UNLOAD. 


6.4.9 Sense Tape Mode 

The sense tape mode function senses the current device-dependent and 
extended device characteristics (see Tables 6-3 and 6-4). 

The VMS operating system provides the following function codes: 

• IO$_SENSEMODE—Sense mode 

• IO$_SENSECHAR—Sense characteristics 

Sense mode requires logical I/O privilege. Sense characteristics requires 
physical I/O privilege. For TMSCP drives the sense mode function returns 
magnetic tape information in a user-supplied buffer, which is specified by the 
following function-dependent arguments: 

• PI—Optional. Address of a user-supplied buffer. 

• P2—Optional. Length of user-supplied buffer. 
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If PI is not zero, the sense mode buffer returns the tape characteristics. (If 
P2=8, the second longword of the buffer contains the device-dependent 
characteristics. If P2=12, the second longword contains the device¬ 
dependent characteristics and the third longword contains the tape 
densities that the drive supports and the extended tape characteristics.) 

The extended characteristics are identical to the information returned by 
DVI$_DEVDEPEND2 (see Table 6-4). Figure 6-3 shows the contents of the 
PI buffer. 

Regardless of whether the PI buffer is specified, the I/O status block returns 
the device-dependent characteristics in the second longword (see Figure 6-6). 
These characteristics are identical to the information returned by 
DVI$_DEVDEPEND (see Table 6-3 in Section 6.3). 


Figure 6-3 Sense Mode PI Buffer 


P2=8: 

31 

15 

16 8 

7 

0 

buffer size 

type 

class 

tape characteristics* 

•from UCB$I_DEVDEPEND 

P2=12: 





31 

15 

16 8 

7 

0 

buffer size 

type 

class 

tape characteristics* 

extended tape characteristics** 

supported densities** 


•from UCB$I_DEVDEPEND 

••from UCB$I_DEVDEPND2 


ZK-4854-85 


6.4.10 Set Mode 


Set mode operations affect the operation and characteristics of the associated 
magnetic tape device. The VMS operating system defines two types of set 
mode functions: set mode and set characteristics. 

Set mode requires logical I/O privilege. Set characteristics requires physical 
I/O privilege. The following function codes are provided: 

• IO$—SETMODE—Set mode 

• IO$_SETCHAR—Set charactersitics 

These functions take the following device- or function-dependent arguments 
(other arguments are ignored): 

• PI—The address of a characteristics buffer 
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• P2—Optional. The length of the characteristics buffer. Default is eight 

bytes. If a length of 12 bytes is specified, the third longword (which is for 
TMSCP drives only) specifies the extended tape characteristics. 

Figure 6-4 shows the PI characteristics buffer for IO$_SETMODE. Figure 6-5 
shows the same buffer for IO$_SETCHAR. 

Figure 6-4 Set Mode Characteristics Buffer 


P2=8: 

31 1615 0 


buffer size 

not used 

tape characteristics 


P2=12: 

31 16 15 0 


buffer size 

not used 

tape characteristics 

extended tape characteristics 

reserved 


ZK-4856-85 
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Figure 6-5 Set Characteristics Buffer 
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The first longword of the PI buffer for the set characteristics function contains 
information on device class and type, and the buffer size. The device class for 
tapes is DC$_TAPE. 

The $DCDEF macro defines the device type and class names. The buffer 
size is the default to be used for tape transfers (this default is normally 2048 
bytes). 

The second longword of the PI buffer for both the set mode and set 
characteristics functions contains the tape characteristics. Table 6-6 lists 
the tape characteristics and their meanings. The $MTDEF macro defines 
the symbols listed. If P2=12, the third longword contains the extended tape 
characteristics for TMSCP drives, which are listed in Table 6-7. Thegextended 
tape characteristics are defined by the $MT2DEF macro and are identical to 
the information returned by DVI$_DEVDEPEND2. 

Table 6-6 Set Mode and Set Characteristics Magnetic Tape 
Characteristics 

Characteristic 1 Meaning 

MT$M_PARITY If set, all data transfers are performed with even parity. 

If clear (normal case), all data transfers are performed 
with odd parity. Even parity can be selected only for non- 
return-to-zero-inverted recording at 800 bpi. Even parity 
cannot be selected for phase-encoded recording (tape 
density is MT$K_PE_1600) or group-coded recording 
(tape density is MT$K_GCR_6250) and is ignored. 


1 Defined bv the $MTDEF macro 
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Table 6-6 (Cont.) Set Mode and Set Characteristics Magnetic Tape 
Characteristics 

Characteristic 1 Meaning 


MT$V_DENSITY 

MT$S_DENSITY 


MT$V_FORMAT 

MT$S_FORMAT 


Specifies the density at which all data transfers are 
performed. Tape density can be set only when the 
selected drive's tape position is at the BOT marker. 
Possible density values are as follows: 

MT$K_DEFAULT Default system density. 

MT$K_GCR_6250 Group-coded recording, 6250 bpi. 

MT$K_PE_1600 Phase-encoded recording, 1600 

bpi. 


MT$K_NRZI_800 

MT$K_BLK_833 


Non-return-to-zero-inverted 
recording, 800 bpi. 

Cartridge block mode recording 2 . 


Specifies the format in which all data transfers are 
performed. Possible format values are as follows: 
MT$K_DEFAULT Default system format. 

MT$K_NORMAL11 Normal PDP-11 format. Data bytes 

are recorded sequentially on tape 
with each byte occupying exactly 
one frame. 


defined by the SMTDEF macro 
2 0nly for the TK50, TZ30, and TF30 


Table 6-7 Extended Device Characteristics for Tape Devices 
Characteristic 1 Meaning 


MT2$V_WBC_ENABLE 

MT2$V_RDC_DISABLE 


Enable write-back caching on a per unit basis. 
Disable read caching on a per unit basis. 


defined by the $MT2DEF macro. Only for TU81-Plus drives. 


Application programs that change specific magnetic tape characteristics should 
perform the following steps, as shown in Example 6-2 in Section 6.6: 

1 Use the IO$_SENSEMODE function to read the current characteristics. 

2 Modify the characteristics. 

3 Use the set mode function to write back the results. 


Failure to follow this sequence will result in clearing any previously set 
characteristic. 
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6.4.11 Data Security Erase 

The data security erase function erases all data from the current position of 
the volume to 10 feet beyond the EOT reflective strip and then rewinds the 
tape to the BOT marker. It is a physical I/O function and requires the access 
privilege necessary to perform physical I/O functions. It is applicable only 
for the TA78, TU78, TA81, TK50, TU81, TU81-Plus, TZ30, and TF30 drives. 
The following function code is provided: 

• IO$_DSE 

If the function is issued when a tape is positioned at the BOT marker, all data 
on the tape will be erased. 

IO$__DSE takes no device- or function-dependent arguments. 


6.4.12 Pack Acknowledge 

The pack acknowledge function sets the volume valid bit for all magnetic 
tape devices. It is a physical I/O function and requires the access privilege to 
perform physical I/O. The following function code is provided: 

• IO$—PACKACK 

This function code takes no function-dependent arguments. 

IO$—PACKACK must be the first function issued when a volume is placed in 
a magnetic tape drive. IO$__PACKACK is issued automatically when the DCL 
commands INITIALIZE or MOUNT are issued. 


6.4.13 Available 

The available function clears the volume valid bit for all magnetic tape drives, 
that is, it reverses the function performed by the pack acknowledge function 
(see Section 6.4.12). A rewind of the tape is performed (applicable to all tape 
drives). No unload function is issued to the drive. The following function 
code is provided: 

• IO$_AVAILABLE 

This function takes no function-dependent arguments. 


6.5 I/O Status Block 

The I/O status block (IOSB) for QIO functions on magnetic tape devices is 
shown in Figure 6-6. Appendix A lists the status returns for these functions. 
(The VMS System Messages and Recovery Procedures Reference Volume provides 
explanations and suggested user actions for these returns.) Table 6-3 (in 
Section 6.3) lists the device-dependent data returned in the second longword. 
The IO$_SENSEMODE function can be used to return that data. 
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6.5 I/O Status Block 


Figure 6-6 IOSB Contents 


31 16 15 _0 


byte count 

status 

device-dependent data 


ZK-675-82 


The byte count is the actual number of bytes transferred to or from the 
process buffer or the number of files or blocks skipped. (If a 
IO$_SKIPRECORD function is terminated by the detection of a tape mark, 
the count returned in the IOSB is a signed number reflecting the number 
of blocks skipped, plus 1 (forward tape motion) or minus 1 (reverse tape 
motion). 


Programming Examples 

The following program (Example 6-1) is an example of how data is written to 
and read from magnetic tape. In the example, QIO operations are performed 
through the magnetic tape ACP. These operations could have been performed 
directly on the device using a magnetic tape driver. However, this would 
have involved additional programming such as writing header labels and 
trailer labels. 
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6.6 Programming Examples 


Example 6-1 Magnetic Tape Program Example 


********************************************************************* 


.TITLE MAGTAPE PROGRAMMING EXAMPLE 
.IDENT /01/ 


Define necessary symbols. 

$FIBDEF ;Define file information block 

;symbols 

$I0DEF ;Define I/O function codes 

Allocate storage for the necessary data structures. 


Allocate magtape device name string and descriptor. 


TAPENAME: 

.LONG 20$-10$ 
.LONG 10$ 

10$: .ASCII /TAPE/ 

20 $: 


Length of name string 
Address of name string 
Name string 
Reference label 


Allocate space to store assigned channel number. 


TAPECHAN: ; 

.BLKW 1 ;Tape channel number 

; Allocate space for the I/O status quadword. 


IOSTATUS: ; 

.BLKQ 1 ;I/0 status quadword 

; Allocate storage for the input/output buffer. 

BUFFER: ; 

.REPT 256 ;Initialize buffer to 

.ASCII /A/ ;contain 'A' 

.ENDR ; 

; Now define the file information block (FIB), which the ACP uses 

; in accessing and deaccessing the file. Both the user and the ACP 
; supply the information required in the FIB to perform these 
; functions. 


Example 6-1 Cont'd. on next page 
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6.6 Programming Examples 


Example 6-1 (Cont.) Magnetic Tape Program Example 


FIB.DESCR: 


;Start of FIB 


.LONG 

ENDFIB-FIB 

;Length of FIB 


.LONG 

FIB 

;Address of FIB 

FIB: 

.LONG 

FIB$M_WRITE!FIB$M_ 

.NOWRITE ;Read/write access allowed 


.WORD 

0,0,0 

;File ID 


.WORD 

0,0,0 

;Directory ID 


.LONG 

0 

;Context 


.WORD 

0 

;Name flags 


.WORD 

0 

;Extend control 

ENDFIB: 



;Reference label 


Now define the file name string and descriptor. 


NAME.DESCR: 

.LONG 

.LONG 

NAME: .ASCII 

END.NAME: 


END.NAME-NAME 

NAME 

"MYDATA.DAT;1" 


;File name descriptor 
;Address of name string 
;File name string 
;Reference label 


Start Program 

3|e3|e)|c$3|e9|e3jc$9|e$3|e$3ie3|c$3ic$3ic3|c$3ic$$3te$$$$9|c$)|e3|e$$9{e3|e3|c3jc9|e3|c9|e3|e9|e9|e3fe3|e3|e3|c>|e3|e9|e9|e3|e3|c9|e3{c>|e)|c3ic3|e3{c9|e:fe3|e3|c3tc3|c3{e3|e 


The program first assigns a channel to the magnetic tape unit and 
then performs an access function to create and access a file called 
MYDATA.DAT. Next, the program writes 26 blocks of data (the letters 
of the alphabet) to the tape. The first block contains all A's, the 
next, all B's, and so forth. The program starts by writing a block of 
256 bytes, that is, the block of A's. Each subsequent block is reduced 
in size by two bytes so that by the time the block of Z's is written, 
the size is only 206 bytes. The magtape ACP does not allow the reading 
of a file that has been written until one of three events occurs: 

1. The file is deaccessed. 

2. The file is rewound. 

3. The file is backspaced. 

In this example the file is backspaced zero blocks and then read in 
reverse (incrementing the block size every block); the data is 
checked against the data that is supposed to be there. If no data 
errors are detected, the file is deaccessed and the program exits. 

.ENTRY MAGTAPE.EXAMPLE,~M<R3.R4,R5,R6,R7,R8> 


First, assign a channel to the tape unit. 


$ASSIGN_S TAPENAME,TAPECHAN ;Assign tape unit 
CMPW #SS$_N0RMAL,RO ;Success? 

BSBW ERRCHECK ;Find out 


Now create and access the file MYDATA.DAT. 


Example 6—1 Cont'd. on next page 
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Example 6-1 (Cont.) Magnetic Tape Program Example 


$QI0W_S 

CHAN=TAPECHAN,- 

;Channel is magtape 


FUNC=#IO$_CREATE!IO$M_ACCESS!IO$M_CREATE,-;Function 


- 

;is create 


I0SB=I0STATUS,- 

;Address of I/O status 


- 

; word 


P1=FIB_DESCR,- 

;FIB descriptor 


P2=#NAME_DESCR 

;Name descriptor 

CMPW 

#SS$_N0RMAL,R0 

;Success? 

BSBW 

ERRCHECK 

;Find out 

; L00P1 consists of writing the alphabet 
; description). 

to the tape (see previous 

MOVL 

#26,R5 

;Set up loop count 

MOVL 

#256,R3 

;Set up initial byte count 
;in R3 

L00P1: 


;Start of loop 

$QI0W_S 

CHAN=TAPECHAN,- 

;Perform QIOW to tape channel 


FUNC=#IO$_WRITEVBLK,- 

;Function is write virtual 


- 

;block 


P1=BUFFER,- 

;Buffer address 


P2=R3 

;Byte count 

CMPW 

#SS$_N0RMAL,RO 

;Success? 

BSBW 

ERRCHECK 

;Find out 

; Now decrement 

the byte count in preparation for the next write 

; operation and 

set up a loop count for updating the character 

; written; L00P2 performs the update. 


SUBL2 

#2 ,R3 

;Decrement byte count for 
;next write 

MOVL 

R3,R8 

;Copy byte count to R8 for 
;L00P2 count 

MOVAL 

BUFFER,R7 

;Get buffer address in R7 

L00P2: INCB 

(R7) + 

;Increment character 

SOBGTR 

R8,L00P2 

;Until finished 

SOBGTR 

R5.L00P1 

;Repeat L00P1 until alphabet 
;complete 


The alphabet is now complete. Fall through L00P1 and update the 
byte count so that it reflects the actual size of the last block 
written to tape. 

ADDL2 #2,R3 ;Update byte count 


The tape is now read, but first the program must perform one of 
the three functions described previously before the ACP allows 
read access. The program performs an ACP control function, 
specifying skip zero blocks. This is a special case of skip reverse 
and causes the ACP to allow read access. 


Example 6-1 Cont'd. on next page 
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Example 6—1 (Cont.) Magnetic Tape Program Example 


CLRL FIB+FIB$L_CNTRLVAL ;Set up to space zero blocks 

MOVW #FIB$C_SPACE,FIB+FIB$W_CNTRLFUNC ;Set up for space 

;function 

$QI0W_S CHAN=TAPECHAN,- ;Perform QIOW to tape channel 

FUNC=#I0$_ACPC0NTR0L,- ;Perform an ACP control 


P1=FIB_DESCR 
CMPW #SS$_N0RMAL,RO 

BSBW ERRCHECK 


Read the file in reverse. 


MOVL #26,R5 

MOVB #~A/Z/,R6 

L00P3: 

MOVAL BUFFER,R7 

$QI0W_S CHAN=TAPECHAN,- 

FUNC=#IO$_READVBLK 

I0SB=I0STATUS,- 
P1=BUFFER,- 
P2=R3 

CMPW #SS$_N0RMAL,RO 

BSBW ERRCHECK 


;function 
;Define the FIB 
;Success? 

;Find out 


;Set up loop count 

;Get first character in R6 

;And buffer address to R7 
;Channel is magtape 
IO$M_REVERSE,- ;Function is read 
;reverse 

;Define I/O status quadword 
;And buffer address 
;R3 bytes 
;Success? 

;Find out 


Check the data read to verify that it matches the data written. 


MOVL R3.R4 
CHECKDATA: 

CMPB (R7)+,R6 
BNEQ MISMATCH 
SOBGTR R4,CHECKDATA 
DECB R6 
ADDL2 #2,R3 

SOBGTR R5,L00P3 


;Copy R3 to R4 for loop count 

;Check each character 

;If error, print message 

;Continue until finished 

;Go through alphabet in reverse 

;Update byte count by 2 for 

;next block 

;Read next block 


Now deaccess the file. 


$QI0W_S CHAN=TAPECHAN,- 

FUNC=#IO$_DEACCESS,- 
I0SB=I0STATUS 


Channel is magtape 
Deaccess function 
I/O status 


Deassign the channel and exit. 


EXIT: $DASSGN_S CHAN=TAPECHAN 

RET 


;Deassign channel 
;Exit 


If an error had been detected, a program would normally 
generate an error message here. But for this example the 
program simply exits. 


Example 6-1 Cont'd. on next page 
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Example 6-1 (Cont.) Magnetic Tape Program Example 


MISMATCH: 


BRB 

EXIT 

;Exit 

BNEQ 

EXIT 

;If not success, exit 

RSB 


;Otherwise, return 

.END 

MAGTAPE.EXAMPLE 



The following example (Example 6-2) illustrates the recommended sequence 
for changing a device characteristic. Retrieve the current characteristics using 
a IO$_SENSEMODE request, set the new characteristics bits, and then use 
IO$_SETMODE to set the new characteristics. 

Example 6-2 Device Characteristic Program Example 


$QI0W_S 


FUNC 

= #I0$_SENSEM0DE,- 

CHAN 

= CHANNEL,- 

IOSB 

= IO.STATUS,- 

PI 

= BUFFER,- 

P2 

= #12 


Get current characteristics 

- Sensemode 

- Channel 

- IOSB 

- User buffer supplied 

- Buffer length = 12 


(Check for errors) 


(Set desired characteristics bits) 


$QI0W_S - 


FUNC 

= #I0$_SETM0DE,- 

CHAN 

= CHANNEL,- 

IOSB 

= I0J3TATUS.- 

PI 

= BUFFER,- 

P2 

= #12 


Set new characteristics. 

- Set Mode 

- Channel 

- IOSB 

- User buffer address 

- Buffer length = 12 


(Check for errors) 


The following example (Example 6-3) shows ways of specifying sense mode 
and set mode, both with and without a user buffer specified, and with user 
buffers of different lengths. 
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Example 6-3 Set Mode and Sense Mode Program Example 


.PSECT 

SIODEF 

DEVICE.NAME: 

.ASCID 

CHANNEL: 

.WORD 
BUFFER: .BLKL 

IO.STATUS: 

.QUAD 

.PSECT 

.ENTRY 


IMPURE, NOEXE, NOSHR 


/MUAO/ 


Name of device 

VMS channel to device 

Set/Sense characteristics 
buffer 

Final I/O status 


CODE, RD, NOWRT, EXE 
MAIN,~M<> 


$ASSIGN_S - 



Assign a channel to device 


DEVNAM 

= 

DEVICE_NAME,- 



CHAN 

= 

CHANNEL 


BSBW 

ERR.CHECK2 



Check for errors 

$QI0W_S 

- 



Get current characteristics 


FUNC 

= 

#I0$_SENSEM0DE,- 

No user buffer supplied 


CHAN 

= 

CHANNEL,- 



IOSB 

= 

I0_STATUS 


BSBW 

ERR_CHECK 



Check for errors 

$QI0W_S 

- 



Get current characteristics 


FUNC 

= 

#I0$_SENSEM0DE,- 

User buffer supplied, length 


CHAN 

= 

CHANNEL,- 

defaulted 


IOSB 

= 

I0_STATUS,- 



PI 

= 

BUFFER 


BSBW 

ERR.CHECK 



Check for errors 

$QI0W_S 

- 



Get current characteristics 


FUNC 

= 

#I0$_SENSEM0DE,- 

User buffer supplied, length 


CHAN 

= 

CHANNEL,- 

= 8 


IOSB 

= 

IO.STATUS,- 



PI 

= 

BUFFER,- 



P2 

= 

#8 


BSBW 

ERR.CHECK 



Check for errors 

$QI0W_S 

- 



Get extended characteristics 


FUNC 

= 

#I0$_SENSEM0DE,- 

User buffer supplied, length 


CHAN 

= 

CHANNEL,- 

= 12 


IOSB 

= 

IO.STATUS,- 



PI 

BUFFER,- 



P2 

#12 


BSBW 

ERR.CHECK 



Check for errors 


Example 6-3 Cont'd. on next page 
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Example 6-3 (Cont.) Set Mode and Sense Mode Program Example 



$QI0W_S - 

FUNC 

CHAN 

IOSB 

PI 

= #IO$_SETMODE,- ; 
= CHANNEL.- I 
= IO_STATUS,- ; 
= BUFFER ; 

Set new characteristics 

Length defaulted 


BSBW ERR_CHECK 


Check for errors 


$QI0W_S - 

FUNC 

CHAN 

IOSB 

PI 

P2 

= #IO$_SETMODE,- 
= CHANNEL,- 
= IO_STATUS,- 
= BUFFER,- 
= #8 

Set new characteristics 
Length = 8 


BSBW ERR.CHECK 


Check for errors 


$QI0W_S - 

FUNC 

CHAN 

IOSB 

PI 

P2 

= #IO$_SETMODE,- 
= CHANNEL,- 
= IO_STATUS,- 
BUFFER,- 
#12 

Set extended characteristics 
Length = 12 


BSBW ERR.CHECK 


Check for errors 


RET 




.ENABLE LSB 



ERR CHECK: 

BLBS I0_STATUS,ERR_CHECK2 

MOVZWL I0_STATUS,-(SP) 

BRB 10$ 

; Continue if good IOSB 
; Otherwise, set up for stop 
; Branch to common code 

ERR.CHECK2: 

BLBS RO,20$ 

PUSHL RO 

10$: CALLS #1,G~LIB$ST0P 

; Continue if good status 
; Otherwise, set up for stop 
; Stop execution 

20$: 

RSB 




.DISABLE LSB 




.end main 
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7 Mailbox Driver 


€ 


The VMS operating system supports a virtual device, called a mailbox, 
that is used for communication between processes. Mailboxes provide 
a controlled and synchronized method for processes to exchange data. 
Although mailboxes transfer information much like other I/O devices, they 
are not hardware devices. Rather, mailboxes are a software-implemente 
ways to perform read and write operations. 


Multiport memory mailboxes function in the same way as regular mailboxes. 
They can also be used by processes on different processors connected to an 
MA780 multiport memory option. 


The Guide to VMS Programming Resources and the VMS System Services 
Reference Manual contain additional information on the use of mailboxes. 



Mailbox Operations 


Table 7-1 lists the different operations that software mailboxes perform. 


Table 7-1 Mailbox Read and Write Operations 


Operation 

Receive mail 


Receive notification 
of mail 

Send mail (without 
notification of 
receipt) 


Send mail (with 
notification of 
receipt) 

Reject mail 


Description 

A process initiates a read request to a mailbox to 
obtain data sent by another process. The process 
reads the data if a message was previously 
transmitted to the mailbox. 

A process specifies that it be notified through an 
AST when a message is sent to the mailbox. 

A process initiates a write request to another 
mailbox to transmit data to second process. The 
sending process does not wait until the data is 
read by the receiving process before completing 
the I/O operation. 

A process initiates a write request to another 
mailbox to transmit data to second process. The 
sending process waits until the receiving process 
reads the data before completing the I/O operation. 

The receiving process reads messages from the 
mailbox, sorts out unwanted messages, and 
responds only to useful messages. 


7.1.1 Creating Mailboxes 


To create a mailbox and assign a channel and logical name to it, a process 
uses the Create Mailbox and Assign Channel ($CREMBX) system service. The 
system enters the logical name in the job logical name table and gives it an 
equivalence name of MBAn, where n is a unique unit number. 
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$CREMBX also establishes the characteristics of the mailbox. These 
characteristics include a protection mask, permanence indicator, maximum 
message size, and buffer quota. A mailbox is created as either a temporary 
mailbox or a permanent mailbox; both types of mailboxes require privilege 
to create. Applications and restrictions on use of temporary and permanent 
mailboxes are described in the sections that follow. (See the VMS System 
Services Reference Manual for additional information on creating mailboxes.) 


ca A n assi § n additional channels to the mailbox using either 
SCREMBX or the Assign I/O Channel ($ASSIGN) system service. The 
mailbox is identified by its logical name both when it is created and when it 
is assigned channels by cooperating processes. 


Figure 7-1 illustrates the use of $CREMBX and $ASSIGN. 


If sufficient dynamic memory for the mailbox data structure is not available 
when a mailbox is created, a resource wait occurs if resource wait mode is 


When a mailbox is created, a certain amount of space is specified for buffering 
messages that have been written to the mailbox, but they have not yet been 
read. The bufquo argument to the $CREMBX system service specifies this 
amount or quota. If that argument is omitted, its value defaults to the system 
generation parameter DEFMBXBUFQUO. 3 

A message written to a mailbox, in the absence of an outstanding read 
request, is queued to the mailbox, and the size of the message (the QIO P2 
argument) is subtracted from the available buffering space. After the message 
is read, it is added back to the available buffering space. 

If a process attempts to write to a mailbox that is full or has insufficient 
uffermg space, and if the process has resource wait enabled (which is the 
e j? u . case )' thf process is placed in miscellaneous resource wait mode until 
sufficient space is available in the mailbox. If resource wait is not enabled 

block (?0SB) P eteS WUh thC St3tUS rCtUm SS$ - MBFULL in the l /° sta tus 


The programming example at the end of this section (Section 7.5) illustrates 
mailbox creation and interprocess communication. 


7.1.2 Deleting Mailboxes 


As each process finishes using a mailbox, it deassigns the channel using 
the Deassign I/O Channel ($DASSGN) system service. The channel count 
is decremented by 1. The system maintains a count of all channels and 
automatically deletes the mailbox when no more channels are assigned to it 
(that is, when the channel count reaches 0). 

If a mailbox channel is deassigned, all messages sent through that channel 

are deleted unless the IO$M_NOW function modifier was specified with the 
wnte request. r 

r«ncr a ^ e R^ maiI . bOXeS mUSt be ex P licitl y deleted using the Delete Mailbox 
(SDELMBX) system service. An explicit deletion can occur at any time. 

assigned^to^t ma ^ b ° X * s actuaF y deleted when no processes have channels 
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Figure 7-1 Multiple Mailbox Channels 



When a temporary mailbox is 
to the process that created it. 
mailboxes.) 


deleted, its message buffer quota is returned 
(No quota charge is made for permanent 


7.1.3 Mailbox Message Format 

There is no standardized format for mailbox messages and none is imposed 
on users. Figure 7-2 shows a typical mailbox message format. Other types 
of messages can take different formats; for an example, see Figure 8-2 in 
Section 8.2.4. 


7.1.4 Mailbox Protection 


Mailboxes (both temporary and permanent) are protected by * cod ®' ° r ™ as ' 
that is similar to the code used in protecting volumes. As wth volumes 
four types of users (defined by UIC) can gam access to a mailbox. SYSTEM, 
OWNER, GROUP, and WORLD. However, only three types of access 
logical I/O, read, and write—are meaningful to users of a mailbox Thus, 
when creating a mailbox, you can specify logical I/O, read, and wnte access 
to r/maUta separately for each type of use. Logical I/O access ts teqtured 
for any mailbox operation. The set protection function modifier provides 
additional control of mailbox access (see Section 7.3.5). 
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7.1 Mailbox Operations 


Figure 7-2 Typical Mailbox Message Format 



Because temporary mailboxes are customarily used for interprocess 
communication between cooperating processes with the same group number, 
they are used more frequently than permanent mailboxes. The logical names 
of these mailboxes are entered in the group logical name table. Temporary 
mailboxes thus have two layers of protection. First, easy access to the logical 
names of temporary mailboxes is granted only to users who have the same 
group number as the creator of the mailbox; other users have no such easy 
access. Second, through the protection mask, the creator of the temporary 
mailbox grants additional security to the mailbox. As a rule, users who are 
not in the same group as the creator are excluded from using the mailbox. 

Furthermore, the creator of a temporary mailbox can distinguish owners 
from other group members by granting read access and write access to a 
temporary mailbox in addition to logical I/O access. For example, owners 
can be allowed only read access or only write access to the mailbox, but other 
members of the group can be allowed both read access and write access to 
the mailbox. 


7.2 


Device Information 


You can obtain information on mailbox characteristics by using the Get 
Device/Volume Information ($GETDVI) system service. (See the VMS System 
Services Reference Manual.) y 


SGETDVI returns mailbox characteristics when you specify the item code 

P, V “" HAR - Table 7-2 lists these characteristics, which are defined by 
the $DEVDEF macro. J 
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7.2 Device Information 


Table 7-2 Mailbox Characteristics 


Characteristic 1 

Meaning 

Dynamic Bits (Conditionally Set) 

DEV$M_SHR 

Device is shareable. 

DEV$M_AVL 

Device is available. 

Static Bits (Always Set) 

DEV$M_REC 

Device is record-oriented. 

DEV$M_IDV 

Device is capable of input. 

DEV$M_ODV 

Device is capable of output. 

DEV$M MBX 

Device is a mailbox. 

1 Defined by the $DEVDEF macro. 


DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device 
type names, which are defined by the $DCDEF macr ^ J h ® device class 
for mailboxes is DC$_MAILBOX. The device type is DT$_MBX (or DT$_ 
SHRMBX if the mailbox is a shared memory mailbox). DVI$_DEVBUFSIZ 
returns the buffer size, which is the maximum message size in bytes. 
DVI$_DEVDEPEND returns a longword field in which the two low-order 
bytes contain the number of messages in the mailbox. (The two high-order 
bytes are not used and should be ignored.) 


DVI$_UNIT returns the mailbox unit number. Use of a mailbox to hold a 
termination message for a subprocess or a detached process requires that the 
parent process obtain this number to pass to the mbxunt argument of the 
$CREPRC system service. 


7.3 


Mailbox Function Codes 

The VMS mailbox I/O functions are read, write, write end-of-file, and set 
attention AST. 


No buffered I/O byte count quota checking is performed on mailbox I/O 
messages. Instead, the byte count or buffer quota of the maiR.ox is checked 
for sufficient space to buffer the message being sent. The buffered I/O quota 
and AST quota are also checked. 
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7.3 Mailbox Function Codes 


7.3.1 Read 

Read mailbox functions are used to obtain messages written by other 
processes. The VMS operating system provides the following mailbox 
function codes: 

• IO$_READVBLK—Read virtual block 

• IO$_READLBLK—Read logical block 

• IO$_READPBLK—Read physical block 

The following device- or function-dependent arguments are used with these 
codes: 

• PI—The starting virtual address of the buffer that is to receive the 
message read. If P2 specifies a zero-length buffer, PI is ignored. 

• ^ ; The s * ze °f buffer in bytes (limited by the maximum message 
size for the mailbox). A zero-length buffer may be specified. If a 
message longer than the buffer is read, the alternate success status 
SS$_BUFFEROVF is returned in the I/O status block. In such cases, 
the message is truncated to fit the buffer. The driver does not provide a 
means for recovering the deleted portion of the message. 

The following function modifier can be specified with a read request: 

IO$M_NOW Complete the I/O operation immediately with no wait for 
a write request from another process 

Figure 7-3 illustrates the read mailbox functions. In this figure, process A 
reads a mailbox message written by process B. As the figure indicates, a 
mailbox read request requires a corresponding mailbox write request (except 
in the case of an error). The requests can be made in any sequence; the read 
request can either precede or follow the write request. 

If process A issues a read request before process B issues a write request, one 

can OCCur ' If process A did not specify the function modifier 
lUq>M—NOW, process A s request is queued before process B issues the write 
request. When this request occurs, the data is transferred from process B, 
through the system buffers, to process A to complete the I/O operation. 

However, if process A did specify the IO$M_NOW function modifier, the 
read operation is completed immediately. That is, process A's request is not 
queued until process B issues the write request, and no data is transferred 
from process B to process A. In this case, the I/O status returned to process A 
is SS$_ENDOFFILE. 

If process B sends a message (with no function modifier; see Section 7 3 2) 
before process A issues a read request (with or without a function modifier), 
process A finds a message in the mailbox. The data is transferred and the I/O 
operation is completed immediately. 

To issue the read request, process A can specify any of the read function 
codes; all perform the same operation. 
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7.3 Mailbox Function Codes 


Figure 7-3 Read Mailbox 



NOTE: Numbers indicate order of events. 


7.3.2 Write 

Write mailbox functions are used to transfer data from a process to a mailbox. 
The VMS operating system provides the following mailbox function codes: 

• IO$_WRITEVBLK—Write virtual block 

• IO$_WRITELBLK—Write logical block 

• IO$_WRITEPBLK—Write physical block 

These function codes take the following device- or function-dependent 
arguments: 

• pi_The starting virtual address of the buffer that contains the message 

being written. If P2 specifies a zero-length buffer, PI is ignored. 

• P2—The size of the buffer in bytes (limited by the maximum message size 
for the mailbox). A zero-length buffer produces a zero-length message to 
be read by the mailbox reader. 

The following function modifiers can be specified with a write request: 

• IO$M_NOW—Complete the I/O operation immediately with no wait for 
another process to read the mailbox message 

• IO$M_NORSWAIT—If the mailbox is full, the I/O operation fails with a 
status return of SS$_MBFULL rather than placing the process in resource 
wait mode 

Figure 7-4 illustrates the write mailbox function. In this figure, process A 
writes a message to be read by process B. As in the read request example, a 
mailbox write request requires a corresponding mailbox read request (unless 
an error occurs), and the requests can be made in any sequence. 

If process A issues a write request before process B issues a read request, one 
of two events can occur. If process A did not specify the function modifier 
IO$M_NOW, process A's write request is queued before process B issues a 
read request. When this request occurs, the data is transferred from process A 
to process B to complete the I/O operation. 
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However, if process A did specify the IO$M_NOW function modifier, the 
write operation is completed immediately. The data is available to process B 
and is transferred when process B issues a read request. 

If process B issues a read request (with no function modifier) before process 
A issues a write request (with or without the function modifier), process A 
finds a request in the mailbox. The data is transferred and the I/O operation 
is completed immediately. 

To issue the write request, process A can specify any of the write function 
codes; all perform the same operation. 

Figure 7-4 Write Mailbox 



NOTE: Numbers indicate order of events. 
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7.3.3 Write End-of-File Message 

Write end-of-file message functions are used to insert a special message in 
the mailbox. The process that reads the end-of-file message is returned the 
status code SS$_ENDOFFILE in the I/O status block. No data is transferred, 
This function takes no arguments. The VMS operating system provides the 
following function code: 

• IO$_WRITEOF—Write end-of-file message 

The following function modifier can be specified with a write end-of-file 
request: 

• IO$M_NOW—Complete the I/O operation immediately 
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7.3 Mailbox Function Codes 


7.3.4 Set Attention AST 

Set attention AST functions are used to specify that an AST be delivered to 
the requesting process when a cooperating process places an unsolicited read 
or write request in a designated mailbox. If a message exists in the mailbox 
when a request to enable a write attention AST is issued, the AST routine is 
activated immediately. If no message exists, the AST is delivered when a read 
or write message arrives. Thus the requesting process need not repeatedly 
check the mailbox status. You must have both logical I/O and read access to 
the mailbox prior to performing a set attention AST function. 

The VMS operating system provides the following function codes: 

• IO$_SETMODE!IO$M-READATTN—Read attention AST 

• IO$_ SETMODE!IO$M_WRTATTN—Write attention AST 

These function codes take the following device- or function-dependent 
arguments: 

• pi—AST address (request notification is disabled if the address is 0) 

• P2—AST parameter returned in the argument list when the AST service 
routine is called 

. p 3 —Access mode to deliver AST; maximized with requester's mode 

These functions are enabled only once; they must be explicitly reenabled after 
the AST has been delivered if you desire notification of the next unsolicited 
request. Both types of enable functions, and more than one of each type, can 
be set at the same time. The number of enable functions is limited only by 
the AST quota for the process. 

Figure 7-5 illustrates the write attention AST function. In this figure, an AST 
is set to notify process A when process B sends an unsolicited message. 

Process A uses the IO$_SETMODE!IO$M_WRTATTN function to request an 
AST. When process B sends a message to the mailbox, the AST is delivered 
to process A. Process A responds to the AST by issuing a read request to the 
mailbox. The function modifier IO$M_NOW is included in the read request. 
The data is then transferred to complete the I/O operation. 

If several requesting processes have set ASTs for unsolicited messages at the 
same mailbox, all ASTs are delivered when the first unsolicited message is 
placed in the mailbox. However, only the first process to respond to the Abl 
with a read request receives the data. Thus, when the next process to respond 
to an AST issues a read request to the mailbox, it might find J}>° x 

empty. If this request does not include the function modifier IO$M_NOW, it 
is queued before the next message arrives in the mailbox. 

Figure 7-6 illustrates the read attention AST function. In this figure, an AST 
is set to notify process A when process B issues a read request for which no 
message is available. 

Process A uses the IO$_SETMODE!IO$M-READATTN function to specify 
an AST When process B issues a read request to the mailbox, the Ab 1 is 
delivered to process A. Process A responds to the AST by sending a message 
to the mailbox. The data is then transferred to complete the I/O operation. 


7-9 









Mailbox Driver 

7.3 Mailbox Function Codes 


Figure 7-5 Write Attention AST (Read Unsolicited Data) 



NOTE: Numbers indicate order of events. 


Figure 7-6 Read Attention AST 



NOTE: Numbers indicate order of events. 

ZK-682-82 


If several requesting processes set ASTs for read requests for the same 
mailbox, all ASTs are delivered when the first read request is placed in the 
mailbox. Only the first process to respond with a write request is able to 
transfer data to process B. 
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7.3 Mailbox Function Codes 


7.3.5 


Set Protection 


Set orotection functions allow the user to set volume protection on a mailbox 
(see P Section 7 1.4). The requester must either be the owner of the mailbox or 
have BYPASS privilege. The VMS operating system provides the following 

function code: 

• IO$_SETMODE!IO$M_SETPROT—Set protection 

This function code takes the following device- or function-dependent 
argument: 

• P2—A volume protection mask 

The protection mask specified by P2 is a 16-bit mask with four bits for each 
class P of owner: SYSTEM, OWNER, GROUP, and WORLD, as shown in 
Figure 7-7. 

Figure 7-7 Protection Mask 
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Onlv logical I/O, read, and write functions have meaning for 

dear (of bit implies that access is allowed. If P2 is 0 or unspecified, the ma 
is set to allow all read, write, and logical operations. 

The I/O status block for the set protection function (see Figure 7-10) returns 
SS$_ NORMAL in the first word if the request was 

was not successful, the $QIO system service returns SS$_NOPRIV and both 
longwords of the I/O status block are returned as zeros. 
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7.3 Mailbox Function Codes 


e set protection function is typically used when you want to inhibit write 
access and thus close off input to the mailbox. The mailbox can then be 

emptied without concern that a write operation might coincide with the read 
operation. 


e JO status blocks (IOSB) for mailbox read, write, and set protection QIO 
functions are shown in Figures 7-8, 7-9, and 7-10. 

Appendix A lists the I/O status returns for these functions. In addition to 
these returns, the system services status returns SS$_ACCVIO 
SS$_INSFMEM, SS$_MBFULL, SS$_MBTOOSML, and SS$_NOPRIV can be 

EtloviJ' The i VM f- S y stem , Messa S es and Recovery Procedures Reference 
Volume provides explanations and suggested user actions for both types of 
returns.) J r 

Figure 7—8 IOSB Contents - Read Function 
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Figure 7 9 IOSB Contents - Write Function 
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Figure 7-10 IOSB Contents - Set Protection Function 


IOSB 
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The following program (Example 7-1) creates a mailbox and puts mail into 
it; no matching"read is pending on the mailbox. First, the program illustrates 
that if the function modifier IO$M_NOW is not used when mail is deposited, 
the write function waits until a read operation is performed. In this case 
IO$M_NOW is specified and the program continues after the mail is lett in 

the mailbox. 

Next the mailbox is read. If there is no mail in the mailbox, the program 
waits because IO$M_NOW is not specified. IO$M_NOW should be specified 
if there is any doubt about the availability of data in the mailbox, and it is 
important for the program not to wait. 

It is up to the user to coordinate the data that goes into and out of mailboxes. 
In this P example the process reads its own message. Normally, two mailboxes 
are used for interprocess communication: one for sending data from process 
A to process B, and one for sending data from process B to process A. If 
a program is arranged in this manner, there is no possibility of a process 
reading its own message. 
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Example 7-1 Mailbox Driver Program Example 

: ********************************************************************* 


•TITLE MAILBOX DRIVER PROGRAM EXAMPLE 
.IDENT /01/ 


Define necessary symbols. 


$I0DEF 


;Define I/O function codes 


Allocate storage for necessary data structures. 


Allocate output device name string and descriptor. 


DEVICE.DESCR: 

.LONG 
• LONG 
10$: .ASCII 

20 $: 


20 $- 10 $ 

10 $ 

/SYS$OUTPUT/ 


;Length of name string 
.Address of name string 
;Name string of output device 
;Reference label 


Allocate space to store assigned channel number. 


DEVICE.CHANNEL: 

,BLKW 1 ;Channel number 


; Allocate mailbox name string and descriptor. 

MAILBOX_NAME: 

• LONG ENDBOX-NAMEBOX 

• LONG NAMEBOX 
NAMEBOX: .ASCII /146_MAIN_ST/ 

ENDBOX: 


Allocate space to store assigned channel number. 


;Length of name string 
;Address of name string 
;Name string 
;Reference label 


MAILBOX.CHANNEL: 

.BLKW 1 

; Allocate space to store the 


;Channel number 

outgoing and incoming messages. 


IN_BOX_BUFFER: 

.BLKB 40 


IN__LENGTH=. - IN_BOX_BUFFER 

OUT.BOX.BUFFER: 

•ASCII /SHEEP ARE VERY DIM/ 
OUT_LENGTH=.-0UT_B0X_BUFFER 


Allocate 40 bytes for 

received message 

Define input buffer length 

Message to send 

Define length of message to 

send 


Example 7—1 Cont # d. on next page 


7-14 




















Mailbox Driver 

7.5 Programming Example 


Example 7-1 (Cont.) Mailbox Driver Program Example 


Finally, allocate space for the I/O status quadword. 


STATUS: 

.QUAD 1 


;I/O status quadword 


********************************************************************* 


Start Program 

********************************************************************* 


The program first creates a mailbox and assigns a channel to the 
process output device. Then a message is placed in the mailbox and 
a message is received from the mailbox (the same message). Finally, 
?he program prints the contents of the mailbox on the process output 

device. 


START: .WORD 0 

$CREMBX_S CHAN=MAILBOX_CHANNEL 
PR0MSK=#~X0000,- 
BUFQU0=#~X0060,- 
LOGNAM=MAILBOX_NAME,- 
MAXMSG=# ~ X0060 
CMPW #SS$_N0RMAL,RO 

BSBW ERROR.CHECK 

$ASSIGN_S - 

DEVNAM=DEVICE_DESCR,- 
CHAN=DEVICE_CHANNEL 
CMPW #SS$_N0RMAL,RO 

BSBW ERROR.CHECK 


;Entry mask 

;Channel is the mailbox 
;No protection 
;Buffer quota is hex 60 
;Logical name descriptor 
;Maximum message is hex 60 
.Successful mailbox creation? 
;Find out 
;Assign channel 
;Device descriptor 
•.Channel 

;Successful channel assign? 
;Find out 


The program now writes to the mailbox using a write request that 
includes the function modifier I0$M_N0W so that it need not wait for 
a read request to the mailbox before continuing to the next step in 
the program. 


$QI0W_S 


CMPW 

BSBW 


FUNC=#IO$_WRITEVBLK!I0$M. 
CHAN=MAILBOX_CHANNEL.- 
P1=0UT_B0X_BUFFER,- 
P2=#0UT_LENGTH 
#SS$.NORMAL.RO 
ERROR.CHECK 


.NOW,- ;Write message NOW 
to the mailbox channel 
Write buffer 
Buffer length 
Successful write request? 
Find out 


; Read the mailbox. 


Example 7-1 Cont'd. on next page 
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Example 7-1 (Cont.) Mailbox Driver Program Example 



$QI0W_S FUNC=#IO$_READVBLK,- 
CHAN=MAILBOX_CHANNEL,- 
IOSB=STATUS,- 

P1=IN_B0X_BUFFER,- 
P2=#IN_LENGTH 
CMPW #SS$_N0RMAL,RO 
BSBW ERROR.CHECK 


;Read the message 
;in the mailbox channel 
;Define status block to 
;receive message length 
;Read buffer 
;Buffer length 
;Successful read request? 
;Find out 


The program now determines how much mail is in the mailbox (this 
information is in STATUS+2) and then prints the mailbox message on 
the process output device. 


MOVZWL STATUS+2,R2 
$QI0W_S FUNC=#IO$_WRITEVBLK,- 
CHAN=DEVICE_CHANNEL,- 
P1=IN_B0X_BUFFER,- 
P2=R2,- 
P4=#32 

Finally, deassign the channel and exit. 


;Byte count into R2 
;Write function to the 
;output device channel 
;Address of buffer to write 
;How much to write 
;Carriage control 


EXIT: $DASSGN__S CHAN=DEVICE_CHANNEL 

RET 


;Deassign channel 
;Return 


This is the error checking part of the program. Normally, some kind 
of error recovery would be attempted at this point if an error was 
detected. However, this example program simply exits. 


ERROR.CHECK: 

BNEQ EXIT 

RSB 

• END START 


System service failure, exit 
Otherwise, return 
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Terminal Driver 


This chapter describes the use of the VMS terminal driver (TTDRIVER) 
and the LAT port driver (LTDRIVER). The terminal driver supports the 
asynchronous^ serial line multiplexers listed in Table 8-1. The termrna dnver 
also supports the console terminal. The LAT port driver accommodates I/O 
requests from application programs, for example to make connections to 
remote devices, such as a printer, on a server (see Section 8.4.4). 


Supported Terminal Devices 

In addition to the multiplexers listed in Table 8-1, the t™f Y d river 
supports serial line interfaces that are included as part of all VAX processors. 
At least one such interface is always provided and is used to attach the 
system console terminal. This interface does not allow the setting of multiple 
terminal speeds, parity, or any maintenance functions, with the exception o 
the interface included with the VAX 8200 processor. The terminal devices 
supported by the VMS operating system for this interface are included in 

Table 8-1. 

The remote command terminal, used by the DCL command SET HOST, also 
makes use of the features listed in Section 8.2. 


Terminal 

Interface 

No. of 
Lines 

Output 

Silo/DMA 

Split 

Speed 

Bus 

International 
Modem Control 

CXY08 

8 

Yes 1 /Yes 

Yes 

Q-BUS 

Full 

CXA16 

16 

Yes 1 /Yes 

Yes 

Q-BUS 

No 

CXB16 

16 

Yes 1 /Yes 

Yes 

Q-BUS 

No 

DZQ11 

4 

No/No 

Yes 

Q-BUS 

No 

DZQ11-CR 

4 

No/No 

Yes 

Q-BUS 

No 

UVAX2000 

4 

No/No 

Yes 

None 

No 

DZV11 

4 

No/No 

No 

Q-BUS 

No 

DHQ11 

8 

Yes’/Yes 

Yes 

Q-BUS 

Full 

DHU11 

16 

Yes/Yes 

Yes 

UNIBUS 

Full 

DHV11 

8 

No/Yes 

Yes 

Q-BUS 

Full 

DMB32 

8 

No/Yes 

Yes 

VAXBI 

Full 

DMF32 

8 

Yes/Yes 

Yes 

UNIBUS 

Yes 



(lines 

(lines 





0 and 1) 

0 and 1) 



DMZ32 

24 

Yes/Yes 

Yes 

UNIBUS 

Full 

DZ11 

8/16 

No/No 

No 

UNIBUS 

No 

'Depends on 

whether the DHV or DHU mode is 

selected when the board is 

installed 
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8.1 Supported Terminal Devices 


Table 8-1 (Cont.) Supported Terminal Devices 


Terminal 

Interface 

No. of 

Lines 

Output 

Silo/DMA 

Split 

Speed 

Bus 

International 

Modem Control 

DZ32 

8 

No/No 

Limited 

UNIBUS 

No 

LAT 

2 

No/Yes 

2 

N/A 

2 

VAX 8200 

4 

No/No 

No 3 

None 

No 

serial lines 







3 The VMS operating system always supports the first serial line as a console interface The first serial line and 
the remaining three serial lines, are also supported as user terminal interfaces at a maximum speed of 1200 baud in 
configurations that may include a LAT terminal interface but do not include other terminaTinTeSs 


8.2 Terminal Driver Features 

The VMS terminal driver provides the following features: 

• Input processing 

— Command line editing and command recall 
— Control characters and special keys 
— Input character validation (read verify) 

American National Standard (ANSI) escape sequence detection 
Type-ahead feature 

— Specifiable or default input terminators 
— Special operating modes, such as NOECHO and PASTHRU 

• Output processing 
— Efficiency 

“ Limited full-duplex operation 
— Formatted or unformatted output 

• Dial-up support 

— Modem control 
— Hangup on logging out 

Preservation of process across hangups 

• Miscellaneous 

— Terminal/mailbox interaction 
Autobaud detection 

— Out-of-band control character handling 
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8.2 Terminal Driver Features 


8 . 2.1 


Input Processing 


The VMS terminal driver defines many terminal characteristics and read 
function modifiers, which provide a wide range of options to an application 
program. These options allow multiple levels of control over the terminal 
driver's input process, ranging from the default of command line editing 
that provides a highly flexible user interface, to the PASTHRU mode, which 
inhibits input process interpretation of data. 


8.2.1.1 Command Une Editing and Command Recall 

The terminal driver input process defines a bounded set of line editing 
functions. These functions are available through control keys on all 
keyboards, and through some special keys on certain keyboards as well. 
Cursor movement is provided in single-character increments (left arrow 
or CTRL/D, right arrow or CTRL/F), or in multicharacter increments, to 
beginning of the line (CTRL/H), or end of the line (CTRL/E). The terminal 
driver supports both insert character and overstrike character modes. 

The insert/overstrike mode is the terminal's default characteristic at the 
beginning of a read operation, but it can be changed dynamically with the 
toggle insert/overstrike key (CTRL/A). Deletion of characters is supported in 
both word (CTRL/J or line feed), and to the beginning of the line (CTRL/U) 
increments. 

When you use the terminal driver's editing functions, the following 
restrictions result: 

• The cursor cannot be moved to a previous line after a line wrap. 

• A character cannot be inserted if the insertion would force a line wrap or 
if a tab follows the current cursor position. 

• A word cannot be deleted at the beginning of a line after a line wrap. 

• The line editing function cannot be assigned to other keys. 

Command recall, initiated by CTRL/B or the up arrow returns the last line 
entered to the command line buffer. At this point, the line can be edited or 
reentered by pressing the RETURN key. DCL extends command recall to 
the last 20 commands by using the TRM$M_TM_NORECALL modifier to 
disable the terminal driver's recall mechanism. 

Any control key that is not defined by line editing is ignored^ For application 
programs that require control key input but do not perform QIO functions 
S Lcial read modifiers, .he SET TERMINAL/NOLINE—EDIT DCL 
command restores most of the terminal driver behavior described under VMS 
Versions 3.0 through 3.7 


1 It is suggested that new users specify overstrike mode. 
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8.2 Terminal Driver Features 


8.2.1.2 


Control Characters and Special Keys 

A control character is a character that controls action at the terminal rather 
than passing data to a process. An ASCII control character has a code 
between 0 and 31, and 127 (hexadecimal 0 through IF, and 7F); that is, all 
normal control characters plus DELETE. (Table 1 in Appendix B lists the 
numeric values for all control characters.) 

Some control characters are entered at the terminal by simultaneously 
pressing the CTRL key and a character key, such as CTRL/x. Table 8-2 
lists the VMS terminal control characters. Control character echo strings 
(CTRL/C CTRL/YCTRL/O, and CTRL/Z) can be changed o“a lyKwide 
„i s i? T ( see the VMS System Generation Utility Manual). Special keys, such as 
RETURN, LINE FEED, and ESCAPE, are entered by pressing a single key 

Several of the control characters do not function as described if the SET 
TERMINAL/LINE—EDIT DCL command is not specified. See the VMS 
DCL Dictionary for information on line editing function keys and the SET 
TERMINAL command. 


Table 8-2 Terminal Control Characters 

Control Character 

Meaning 

Cancel 

(CTRL/C - F6 1 ) 

Gains the attention of the enabling process if the user 
program has enabled a CTRL/C AST. If a CTRL/C AST 
is not enabled, CTRL/C is converted to CTRL/Y (see 
Section 8.4.3.2). 


The terminal performs a carriage-return/line-feed 
combination (carriage return followed by a line feed), 
echoes CANCEL, and performs another carriage-return 
/line-feed combination. If the terminal has the ReGIS 
characteristic or if CTRL/Y is pressed, the cancel ReGIS 
escape sequence is sent. 


Additional consequences of CTRL/C are as follows: 

• The type-ahead buffer is emptied. 

• CTRL/S and CTRL/O are reset. 


• All queued and in-progress write operations and 
all in-progress read operations are successfully 
completed. The status return is SS$_CONTROLC 
or SS$_CONTROLY if CTRL/C is converted to 
CTRL/Y. 

Delete character 
(DELETE) 

Removes the last character entered from the input 
stream. 

’F6 on the LK201 is Interrupt/Cancel. 
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8.2 Terminal Driver Features 


Table 8-2 (Cont.) Terminal Control Characters 


Control Character 


Delete line 
(CTRL/U) 


Delete word 
(CTRL/J or FI3) 
(Line feed) 

Discard output 
(CTRL/O) 


End of line 
(CTRL/E) 

Exit 

(CTRL/Z or F10) 


Meaning___ 

DELETE (decimal 127 or hexadecimal 7F) is ignored 

if there are currently no input characters. Hardcopy 
terminals echo the deleted character enclosed in 
backslashes. For example, if the character z is deleted, 
\z\ is echoed (the second backslash is echoed after the 
next non-DELETE character is entered). Terminals that 
have the TT$M-SCOPE characteristic echo DELETE by 
removing the character. 

Purges current input data. When CTRL/U is entered 
before the end of a read operation, the current input 
line is deleted. (In the case of a line-wrap, CTRL/U 
deletes only a line at a time.) If line editing is enabled 
(SET TERMINAL/LINE-EDIT is specified), the data from 
the beginning of the line to the current cursor position 
is deleted. 

Delete word before cursor. Word terminators are all 
control characters, space, comma, dash, period, and 
I "#$&'() + @[\]“{ | ~/ : • <> =? (see 
Appendix B). 

Discards output. Action is immediate. All output 
is discarded until the next read operation, the next 
write operation with a IO$M_ CANCTRLO modifier, or 
the receipt of the next CTRL/O. The terminal echoes 
OUTPUT OFF. The current write operation (if any) and 
write operations performed while CTRL/O is in effect 
are completed with a status return of SS$_CONTROLO. 

A second CTRL/O, which reenables output, echoes 
OUTPUT ON. CTRL/C, CTRL/Y, and CTRL/T cancel 
CTRL/O. 

Moves the cursor to the end of the line. 

Echoes EXIT when CTRL/Z is entered as a read 
terminator. By convention, CTRL/Z constitutes end-of- 
file. 
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8.2 Terminal Driver Features 


Table 8—2 (Cont.) 

Terminal Control Characters 

Control Character 

Meaning 

Interrupt 

(CTRL/Y) 

CTRL/Y is a special interrupt or attention character 
that is used to invoke the command interpreter for a 
logged-in process. CTRL/Y can be enabled with an 
IO$M_CTRLYAST function modifier to a 

IO$_SETCHAR or IO$_SETMODE function code. The 
command interpreter's CTRL/Y AST handler always 
takes precedence over a user program's CTRL/Y AST 
handler. 

Entering CTRL/Y results in an AST to an enabled 
process to signify that the user entered CTRL/Y 
from the terminal. The terminal performs a carriage- 
return/line-feed combination, echoes INTERRUPT, and 
performs another carriage-return/line-feed combination 
if the AST and echo are enabled. CTRL/Y is ignored 
(and not echoed) if the process is not enabled for the 
AST. 

Additional consequences of CTRL/Y are as follows: 

• The type-ahead buffer is flushed. 

• CTRL/S and CTRL/O are reset. 

• All queued and in-progress write operations and 
all in-progress read operations are successfully 
completed with a 0 transfer count. The status 
return is SS$_CONTROLY. 

• The cancel ReGIS escape sequence is sent. 

Move cursor left 
(CTRL/D <-) 

Move cursor right 
(CTRL/F -) 

Move cursor to 
beginning of line 
(CTRL/H or FI2) 

(Back space) 

Purge type ahead 
(CTRL/X) 

Moves the cursor one position to the left. 

Moves the cursor one position to the right. 

Moves the cursor to the beginning of the line. 

Purges the type-ahead buffer and performs a CTRL/U 
operation. Action is immediate. If a read operation is 
in progress, the operation is equivalent to CTRL/U. 

Recall 

(CTRL/B or 
up arrow) 

Recalls last command entered. DCL extends recall to 
several commands. 
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8.2 Terminal Driver Features 


8.2.1.3 


Table 8-2 (Cont.) Terminal Control Characters 


Control Character 

Redisplay input 
(CTRL/R) 


Restart output 
(CTRL/Q) 


RET 

(RETURN) 


Stop output 
(CTRL/S) 


TAB 

(CTRL/I) 


Status 

(CTRL/T) 


Toggle 

insert/overstrike 
(CTRL/ A or F14) 


Meaning__ 

Redisplays current input. When CTRL/R is entered 

during a read operation, a carriage-return/line-feed 
combination is echoed on the terminal, and the current 
contents of the input buffer are displayed. If the current 
operation is a read with prompt (IO$_READPROMPT) 
operation, the current prompt string is also displayed. 
CTRL/R has no effect if the characteristic 
TT$M—NOECHO is set. 

Controls data flow; used by terminals and the driver. 
Restarts data flow to and from a terminal if previously 
stopped by CTRL/S. The action occurs immediately 
with no echo. CTRL/Q is also used to solicit read 
operations. 

CTRL/Q is meaningless if the line does not have 
the characteristic TT$M_TTSYNC, the characteristic 
TT$M_READSYNC, or is not currently stopped by 
CTRL/S. 

If used during a read (input) operation, RET echoes 
a carriage-return/line-feed combination. All carriage 
returns are filled on terminals with TT$M_CRFILL 
specified. 

Controls data flow; used by both terminals and the 
terminal driver. CTRL/S stops all data flow; the action 
occurs immediately with no echo. CTRL/S is also 
used to stop read operations. CTRL/S is meaningful 
only if the terminal has either the TT$M_TTSYNC 
characteristic or the TT$M —READSYNC characteristic. 

Tabs horizontally. Advances to the next tab stop on 
terminals with the characteristic TT$M_MECHTAB, but 
the terminal driver assumes tab stops on MODULO 8 
(multiples of 8) cursor positions. On terminals without 
this characteristic, enough spaces are output to move 
the cursor to the next MODULO 8 position. 

Displays the current time. CTRL/T also displays 
the current node and user name, the name of the 
image that is running, and information about system 
resources that have been used during the current 
terminal session. 

Changes current edit mode from insert to overstrike, 
or from overstrike to insert. The default mode (as 
set with SET TERMINAL/LINE-EDIT) is reset at the 
beginning of each line. 


Read Verify . , . . „ ... .. 

The read verify instructions provided by the terminal driver allow validation 
of data as each character is entered. Invalid characters are not echoed 
and terminate the operation. The terminal driver does not support full 
function field processing. Large data entry applications should use the VAX 
FMS or VAX TDMS layered products, which support the entire data entry 
environment. Section 8.4.1.4 describes the supported primitives. 
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8.2.1.4 Escape and Control Sequences 

Escape and control sequences provide additional terminal control not 
furnished by the control characters and special keys (see Section 8.2.1.2). 
Escape sequences are strings of two or more characters, beginning with 
the escape character (decimal 27 or hexadecimal IB), which indicate that 
control information follows. Many terminals send and respond to such escape 
sequences to request special character sets or to indicate the position of a 
cursor. 

The set mode characteristic TT$M_ESCAPE (see Table 8-5) is used to 
specify that VMS terminal lines can generate valid escape sequences. Also, 
the read function modifier IO$M_JESCAPE allows any read operation to 
terminate on an escape sequence regardless of whether TT$M_ESCAPE 
is set. If either TT$M_ESCAPE or IO$M_ESCAPE is set, the terminal 
driver verifies the syntax of the escape sequences. The sequence is always 
considered a read function terminator and is returned in the read buffer; 
a read buffer can contain other characters that are not part of an escape 
sequence, but a complete escape sequence always terminates a read operation 
The return information in the read buffer and the I/O status block includes 
the position and size of the terminating escape sequence in the data record 
(see Section 8.5). 

Any escape sequence received from a terminal is checked for correct syntax 

!/S ie ,f y u taX is not COrrect ' ss $—BADESCAPE is returned as the status of the 
I/O. If the escape sequence does not fit in the user buffer, SS$_PARTESCAPE 
is returned. If SS$_PARTESCAPE is returned, the application program must 
issue enough single-character read requests, without timeout, to read the 
remaining characters in the escape sequence, while parsing the syntax of 
the rest of the escape sequence. Use of the TRM$_ESCTRMOVR item code 
prevents SS$_PARTESCAPE errors. No syntax integrity is guaranteed across 
read operations. Escape sequences are never echoed. Valid escape sequences 
take any of the following forms (hexadecimal notation): 

ESC <int>...<int> <fin> (7-bit environment) 

CSI <int>... <int> <fin> (8-bit environment) 

The keywords in the escape sequences indicate the following: 

ESC The ESC key, a byte (character) of IB. This character introduces the 
escape sequence in a 7-bit environment. 

CSI The Control Sequence Introducer, a byte (character) of 9B. This 
character introduces the escape sequence in a 8-bit environment. 

<int> An "intermediate character" in the range of 20 to 2F. This range 

includes the space character and 15 punctuation marks. An escape 
sequence can contain any number of intermediate characters, or none. 

<fin> A " fir| al character" in the range of 30 to 7E. This range includes 

uppercase and lowercase letters, numbers, and 13 punctuation marks. 

Three additional escape sequence forms are as follows: 

ESC <;> <20-2F>..,<30-7E> 

ESC <?> <20-2F>...<30-7E> 

ESC <0> <20-2F>..,<40-7E> 
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8.2.1.5 


Control sequences, as defined by the ANSI standard, are escape sequences 
that include control parameters. Control sequences have the following format: 

ESC [ <par>...<par> <int>...<int> <fin> (7-bit environment) 

CSI <par>...<par> <int>...<int> <fin> (8-bit environment) 

The keywords in the escape sequences indicate the following: 

ESC The ESC key, a byte (character) of IB. 

[ A control sequence, a byte (character) of 5B. 

CSI The Control Sequence Introducer, a byte (character) of 9B. 

<par> A parameter specifier in the range of 30 to 3F. 

<int> An “intermediate character" in the range of 20 to 2F. 

<fin> A “final character" in the range of 40 to 7E. 


For example, the position cursor control sequence is ESC [ PI; Pc H. PI is the 
desired line position and Pc is the desired column position. 

The user guides for the various terminals list valid escape and control 
sequences. For example, the VT100 User Guide lists the escape and control 
sequences for VT100 terminals. 

Section 8.2.1.2 describes control character functions during escape sequences. 


Table 2 in Appendix B lists the valid ANSI and DIGITAL-private escape 
sequences for terminals that have the TT2$M_ANSICRT, TT2$M DECCRT, 
TT2$M_DECCRT2, TT2$M_AVO, TT2$M_EDIT, and TT2$M_BLOCK 
characteristics (see Table 8-6). Table 2 in Appendix B also lists assumed and 
selectable ANSI modes and selectable DIGITAL-private modes. Only the 
names of the escape sequences and modes are listed (for more information 
see the specific user guide for any of the various terminals). Unless otherwise 
noted, the operation of escape sequences and modes is identical to the 
particular terminals that implement these features. 


Type-Ahead Feature 

Input (data received) from a VMS terminal is always independent of 
concurrent output (data sent) to a terminal. This feature is called type-ahead. 
Type-ahead is allowed on all terminals, unless explicitly disabled by the set 
mode characteristic, inhibit type ahead (TT$M_NOTYPEAHD; see Table 8-5 
and Section 8.4.3). 


Data entered at the terminal is retained in the type-ahead buffer until the user 
program issues an I/O request for a read operation. At that time, the data 
is transferred to the program buffer and echoed at the terminal where it was 
typed. 


Deferring the echo until the read operation is active allows the user process 
to specify function code modifiers that modify the read operation. These 
modifiers can include, for example, noecho (IO$M—NOECHO) and convert 
lowercase characters to uppercase (IO$M_CVTLOW) (see Table 8-7). 


If a read operation is already in progress when the data is typed at the 
terminal, the data transfer and echo are immediate. 

The action of the driver when the type-ahead buffer fills depends on the set 
mode characteristic TT$M —HOSTSYNC (see Table 8-5 and Section 8.4.3). 

If TT$M_HOSTSYNC is not set, CTRL/G (BELL) is returned to inform 
you that the type-ahead buffer is full. If characters are entered when the 
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8.2.1.6 


8.2.1.7 


type-ahead buffer is full, the next read operation completes with a status 
return of SS$_DATAOVERUN. If TT$M —HOSTSYNC is set, the driver stops 
input by sending a CTRL/S and the terminal responds by sending no more 
characters. These warning operations begin eight characters before the type- 
ahead buffer fills unless the TT2$M_ALTYPEAHD characteristic is set In 
that case, the system generation parameter TTY—ALTALARM is used. The 
driver sends a CTRL/Q to restart transmission when the type-ahead buffer 
empties completely. 

The type-ahead buffer length is variable, with possible values in the range 
from 0 through 32,767. The length can be set on a systemwide basis through 
use of the system generation parameter TTY—TYPAHDSZ. Terminal lines that 
do a large amount of bulk input should use the characteristic 
TT2$M _ALT YPE AHD, which allows the use of a larger type-ahead buffer 
specified by the system generation parameters TTY—ALTYPAHD and 
TTY_ALTALARM. (TTY—ALTYPAHD specifies the total size of the alternate 
type-ahead buffer; TTY—ALTALARM specifies the threshold at which a 
CTRL/S is sent.) 


Certain input-intensive applications, such as block mode input terminals, 
can take advantage of an optimization in the driver. If a terminal has the 
characteristic TT2$M_PASTHRU and the read function modifier 
IO$M_NOECHO is specified, data is placed directly into the read buffer and 
thereby eliminates the overhead for moving the data from the type-ahead 


Line Terminators 

A line terminator is the control sequence that you type at the terminal to 
indicate the end of an input line. Optionally, the application can specify a 
particular line terminator or class of terminators for read operations. 

Terminators are specified by an argument to the QIO request for a read 
°P er f^°”- Jty default, they can be any ASCII control character except FF, 

VI, LF, TAB, or BS (see Appendix B). If line editing is enabled, the only 
terminators are CR, CTRL/Z, or an escape sequence. Control keys that do not 
have an editing function are nonfunctioning keys. If included in the request, 
the argument is a user-selected group of characters (see Section 8.4.1.2). 

All characters are 7-bit ASCII characters unless data is input on an 8-bit 
terminal (see Section 8.4.1). The characteristic TT$M_EIGHTBIT determines 
whether a terminal uses the 7-bit or 8-bit character set; see Table 8-5. All 
input characters (except some special keys; see Section 8.2.1.2) are tested 
against the selected terminators. The input is terminated when a match 
occurs or your input buffer fills. 


The terminal driver notifies the job controller to initiate login when it detects 
aca ™ge re ^ urn terminator on a line with no current process (provided 
the line is not a secure server or the type-ahead feature has not been 
disabled). A bell character is sent when the notification occurs. A notification 
character other than the bell character may be specified by setting the system 

generation parameter TTY-AUTOCHAR. g me system 


Special Operating Modes 

lTnl V I^ S w erm 0 in c 1 dr i v f su PPOrts many special operating modes for termin; 
lines. (Tables 8 5 and 8-6 in Section 8.3 list these modes.) All special mode 
are enabled or disabled by the set mode and set characteristics functions (see 
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8.2.2 Output Processing 

Output handling is designed to be very efficient in the terminal driver. For 
example, on multiplexers that support both silo and direct memory access 
(DMA) ouput, the driver considers record size to decide dynamically which 
mode will result in the least overhead. The block size specified by the system 
generation parameter TTY_DMASIZE is the minimum size block that can be 
used in a DMA operation. 


8.2.2.1 Duplex Modes 

The VMS terminal driver can execute in either half- or full-duplex mode. 
These modes describe the terminal driver software, specifically the ordering 
algorithms used to service read and write requests, not the terminal 
communication lines. 

In half-duplex mode, all read and write requests are inserted onto one queue. 
The terminal driver removes requests from the head of this queue and 
executes them one at a time; all requests are executed sequentially in the 
order in which they were issued. 

In full-duplex mode, read requests (and all other requests except write 
requests) are inserted onto one queue and write requests onto another. 

The existence of two queues allows the driver to recognize the presence of 
two requests, such as a read request and a write request at the same time. 
However, the driver does not execute the read request and the write request 
simultaneously. When it is ready to service a request, the driver decides 
which request—the read request or the write request—to process next. 

In the VMS terminal driver, write requests usually have priority. A wnte 
request can interrupt a current, but inactive, read request. A read request is 
current when the terminal driver removes that request from the head of the 
read queue. In a read operation, the read request becomes active when the 
first input character is received and echoed. Once a read request becomes 
active, all write requests are queued until the read completes. However, 
during a read operation many write requests can be executed before the 
first input character is entered at the terminal. Terminal lines that have the 

TT$M-NOECHO characteristic, or read functions that include the 

IO$M_NOECHO function modifier, do not inhibit write operations in full- 
duplex mode. 

If a write function specifies the IO$M_BREAKTHRU modifier, the write 
operation is not blocked, even by an active read operation. 

IO$M _BREAKTHRU does not change the order in which wnte operations are 

queued. 

When all I/O requests are entered using the Queue I/O Request and Wait 
($QIOW) system service, there can be only one current I/O request at a time. 
In this case, the order in which requests are serviced is the same for both 
half- and full-duplex modes. 

The type-ahead buffer always buffers input data for which there is no current 
read request, in both half- and full-duplex modes. 
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8.2.2.2 Formatting of Output 

By default, output data is subject to formatting by the terminal driver. This 
formatting includes actions such as wrapping, tab expansion, uppercase, and 
fallback conversions. Applications that do not require formatting of data can 
write with the IO$M—NOFORMAT modifier and thereby reduce overhead. 
IO$M_NOFORMAT overrides all formatting except fallback translation. 
Setting the PASTHRU mode (TT2$M—PASTHRU) is equivalent to writing 
with the noformat modifier. 

Fallback conversions occur regardless of formatting mode. 


8.2.3 Dial-Up Support 


The VMS operating system supports modem control (for example. Bell 103A, 
Bell 113, or equivalent) for all supported multiplexers in autoanswer, full- 
duplex mode. The terminal driver does not support half-duplex operations 
on modems such as the Bell 202. Also not supported are modems that use 
circuit 108/1 (connect data set to line signal) in place of the data terminal 
ready (DTR) signal. Most U.S. and European modems use the data terminal 
ready signal, which is the signal supported by the VMS operating system. 

8.2.3.1 Modem Signal Control 

Dial-up lines with the characteristic TT$M_MODEM are monitored 
periodically to detect a change in the modem carrier signals data set ready 
(DSR), calling indicator (RING), or request to send (RTS). The system 
generation parameter TTY_SCANDELTA establishes the dial-up monitoring 
period for multiplexers that do not support modem signal transition interrupts 
(see Table 8-1). 

If a line's carrier signal is lost, the driver waits two seconds for the carrier 
signal to return. If bit 0 of the system generation parameter TTY—DIALTYPE 
is set to 1, the driver does not wait. Bit 0 is 0 by default for countries with 
Bell System standards, but that bit should be set to 1 for countries with 
Comite Consultatif Internationale (CCITT) standards. If the carrier signal is 
not detected during this time, the line is hung up. The hangup action can 
signal the owner of the line, through a mailbox message, that the line is no 
longer in use. (No dial-in message is sent; the unsolicited character message 
is sufficient when the first available data is received.) The line is not available 
for a minimum of two seconds after the hangup sequence begins. The hangup 
sequence is not reversible. If the line hangs up, all enabled CTRL/Y and out- 
of-band ASTs are delivered; the CTRL/Y AST P2 argument is overwritten 
with SS$_HANGUP. The I/O operation in progress is canceled, and the 
status value SS$_HANGUP is returned in the I/O status block. DCL is 
responsible for process deletion after CTRL/Y is delivered. If the process is 
suspended, DCL cannot run, and therefore deletion cannot occur, until the 
process is resumed. 

For terminals with the TT$M_MODEM characteristic, TT$M_REMOTE 
reflects the state of the carrier signal. TT$M_REMOTE is set when the carrier 
signal changes from off to on, and cleared when the carrier signal is lost. 

A line that does not have TT$M—MODEM set does not respond to modem 
signals or set the DTR signal. Modem signals can be set and sensed manually 
through use of the IO$M_MAINT function modifier (see Section 8.4.3.3). 
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The VMS terminal driver default modem protocol meets the requirements 
of the United States and of European countries. This protocol is capable of 
working in automatic answer mode and can also perform manually dialed 
outgoing calls. The protocol supports the requirements of most known 
international telephone networks. Enhanced modem features are used on 
multiplexers that support them; processor polling is not necessary. The 
protocol also functions in a subset mode for the multiplexers that do not 
support full modem signals (see Table 8-1). 

Table 8-3 lists the control and data signals used in a full modem control 
mode configuration (in a two-way simultaneous, symmetrical transmit mode). 
Figure 8-1 is a flowchart that shows a typical signal sequence for a terminal 
operation in this mode. The flowchart shows the states that the modem 
transition code goes through to detect different types of transitions in modem 
state. These transitions allow the driver to detect loss of lines that have been 
idle for several minutes. Modem states do not affect the ability of the system 
to transmit characters. 

Set mode function modifiers are provided to allow a process to activate or 
deactivate modem control signals (see Section 8.4.3.3). 

Bit 1 of the system generation parameter TTY—DIALTYPE enables alternate 
modem protocol on a systemwide basis. If bit 1 is 0 (the default), the RING 
signal is not used. If bit 1 is 1, the modem protocol delays setting the DTR 
signal until the RING signal is detected. 

Remote terminal connections have a timeout feature for the security of dial¬ 
up lines. If no channel is assigned to the port within 30 seconds, or a port 
with an assigned channel is not allocated, the DTR signal is dropped. Such 
action prevents an unused terminal from tying up a line. However, there are 
configurations (such as a printer connected to a remote line) in which the 
line should not be dropped even though it is not being used interactively. To 
bypass the 30-second timeout, set the system generation parameter 
TTY—DIALTYPE to 4. (Note that if TTY—DIALTYPE is equal to 4, all dial-up 
lines will skip the timeout waiting for a channel to be assigned.) 
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Figure 8—1 Modem Control - Two-Way Simultaneous Operation 
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Table 8-3 Control and Data Signals (Full Modem Mode 
Configuration) _ 

Signal Source MUX 1 Meaning 


Transmitted Computer All 

data (TxD) 


Received data Modem All 

(RxD) 


Request to Computer Full 

send (RTS) 


Clear to send Modem Full 

(CTS) 


Data set ready Modem Full 

(DSR) 


Data channel Modem All 

received line 
signal detector 
(CARRIER) 


The data originated by the 
computer and transmitted 
through the modem to one or 
more remote terminals. 

The data generated by the 
modem in response to telephone 
line signals received from a 
remote terminal and transferred 
to the computer. 

If present (ON condition), RTS 
directs the modem to assume 
the transmit mode. If not 
present (OFF condition), RTS 
directs the modem to assume 
the nontransmit mode after 
all transmit data has been 
transmitted. 

Indicates whether the modem 
is ready (ON condition) or not 
ready (OFF condition) to transmit 
data on the telephone line. 

If present (ON condition), DSR 
indicates that the modem is 
ready to transmit and receive; 
that is, the modem is connected 
to the line and is ready to 
exchange further control signals 
with the computer to initiate the 
exchange of data. 

If DSR is not present (OFF 
condition), the modem is not 
ready to transmit and receive. 

If DSR is detected, the VMS 
operating system initiates a 
30-second timer. This ensures 
that the phone line will be 
disconnected if CARRIER is not 
detected. 

If present (ON condition), 
CARRIER indicates that the 
received data channel line signal 
is within appropriate limits, as 
specified by the modem. If not 
present (OFF condition), the 
received signal is not within 
appropriate limits. 


Multiplexers (All = any supported controller; Full - DZ32, DMF32, DMB32, DMZ32, 
DHU11, DHV11, and CXY08) 
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Table 8-3 (Cont.) Control and Data Signals (Full Modem Mode 
Configuration) 

Signal_Source MUX 1 Meaning 

Data terminal Computer All If present (ON condition), DTR 

ready (DTR) indicates that the computer 

is ready to operate, prepares 
the modem to connect to the 
telephone line, and maintains 
the connection after it has been 
made by other means. DTR 
can be present whenever the 
computer is ready to transmit 
or receive data. If DTR is not 
present (OFF condition), the 
modem disconnects the modem 
from the line. 

Modem All Indicates whether a calling signal 

is being received by the modem. 
Bit 1 of the system generation 
parameter TTY_DIALTYPE must 
be set (=1). If RING is detected, 
the VMS operating system 
initiates a 30-second timer. This 
ensures that the phone line will 
be disconnected if CARRIER is 
not detected. 


Multiplexers (All = any supported controller; Full = DZ32, DMF32, DMB32 DMZ32 
DHU11, DHV11, and CXY08) 


Calling 

indicator 

(RING) 


8.2.3.2 Hangup on Logging Out 

By default, logging out on a line with modem signals will not break the 
connection. If TT2$M—HANGUP is set, modem signals are dropped 
when the process logs out. If TT2$M_MODHANGUP is set, no privilege 
is required to change the state of TT2$M_HANGUP. By setting 
TT2M—HANGUP, system managers can prevent nonprivileged users who are 
not logged in from tying up a dial-in line. 


8.2.3.3 Preservation of a Process Across Hangups 

Disconnectable terminals allow a connection to a physical terminal line to 
be broken without losing the job. The following SYSGEN command allows 
terminals to be disconnectable terminals: 

SYSGEN> CONNECT VTAO/NOADAPTER/DRIVER=TTDRIVER 

After this command is entered, a terminal with the TT2$M_DISCONNECT 
characteristic logs in as VTAn:, rather than with the physical terminal name. 
When a terminal is set up in this manner, no input or output operations 
are allowed to the physical device; I/O is automatically redirected to the 
appropriate virtual terminal. 

Following are four ways in which a terminal can become disconnected: 

• Modem signals between the host and the terminal are lost. 
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• A user presses the BREAK key on a terminal that has the 
TT2$M_SECURE characteristic. 

• A user issues the DCL command DISCONNECT. 

• A user issues the DCL command CONNECT/CONTINUE. 

After validated as a user, you can connect to a disconnected process in either 
of the following ways: 

• Allow the login process to make the connection. 

• Issue the DCL command CONNECT. 


8.2.4 Terminal/Mailbox Interaction 

Mailboxes are virtual I/O devices used to communicate between processes. 
The terminal I/O driver can use a mailbox to communicate with a user 
process. Chapter 7 describes the mailbox driver. 

A user program can use the Assign I/O Channel ($ASSIGN) system service 
to associate a mailbox with one or more terminals. The terminal driver 
sends messages to this mailbox when terminal-related events that require the 
attention of the user image occur. 

Mailboxes used in this way carry status messages, not terminal data, from 
the driver to the user program. For example, when data is received from 
a terminal for which no read request is outstanding (unsolicited data), a 
message is sent to the associated mailbox to indicate data availability. On 
receiving this message, the user program reads the channel assigned to 
the terminal to obtain the data. Messages are sent to mailboxes under the 
following conditions: 

• Unsolicited data in the type-ahead buffer. The use of the associated 
mailbox can be enabled and disabled as a subfunction of the read and 
write requests (see Sections 8.4.1 and 8.4.2). (Initially, mailbox messages 
are enabled on all terminals. This is the default state.) Thus, the user 
process can enter into a dialogue with the terminal after an unsolicited 
data message arrives. Then, after the dialogue is over, the user process 
can reenable the unsolicited data message function on the last I/O 
exchange. Only one message is sent between read operations. 

• Terminal hangup. When a remote line loses the carrier signal, it hangs 
up; a message is sent to the mailbox. When hangup occurs on lines that 
have the characteristic TT$M_REMOTE set, the line returns to local 
mode. 

• Broadcast messages. If the characteristic TT2$M_BRDCSTMBX is 
set, broadcasts sent to a terminal are placed in the mailbox (this is 
independent of the state of TT$M—NOBRDCST). 

Messages placed in the mailbox have the following content and format (see 
Figure 8-2): 

• Message type. The codes MSG$_TRMUNSOLIC (unsolicited data), 
MSG$_TRMHANGUP (hangup), and MSG$_TRMBRDCST (terminal 
broadcast) identify the type of message. Message types are identified by 
the $MSGDEF macro. 

• Device unit number to identify the terminal that sent the message. 
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• Counted string to specify the device name. 

• Controller name. 

• Message (for broadcasts). 

Figure 8-2 Terminal Mailbox Message Format 
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Interaction with a mailbox associated with a terminal occurs through 
standard QIO functions and ASTs. Therefore, the process need not have 
outstanding read requests to an interactive terminal to respond to the arrival 
of unsolicited data. The process need only respond when the mailbox signals 
the availability of unsolicited data. Chapter 7 contains an example of mailbox 
programming. 

The ratio of terminals to mailboxes is not always one to one. One user 
process can have many terminals associated with a single mailbox. 


Autobaud Detection 

If you specify the /AUTOBAUD qualifier with the SET TERMINAL 
command, automatic baud rate detection is enabled, allowing the terminal 
baud rate to be set when you log in. The baud rate is set at login by pressing 
the RETURN key two or more times separated by an interval of at least one 
second. (Pressing a key other than RETURN might detect the wrong baud 
rate; if this occurs, wait for the login procedure to time out before continuing.) 
The supported baud rates are 110, 150, 300, 600, 1200, 1800, 2400, 3600, 
4800, 9600, and 19200. Parity is allowed on these lines. 
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The autobaud function works with either even parity or no parity, but not 
with odd parity. If a line is set to even parity and has seven bits of data, the 
line automatically switches to no parity if a terminal not generating parity 
attempts to log in. 

The SET TERMINAL qualifier /EIGHT_BIT specifies that the terminal uses 
eight-bit ASCII code. /NOEIGHT—BIT, which is the default, specifies seven- 
bit ASCII code. (If parity is specified, the parity bit is separate from the data 
bits) The optimal settings for automatic baud rate detection on DIGITAL 
terminals are /NOEIGHT—BIT/PARITY=EVEN or /EIGHT-BIT/NOPARITY, 
although automatic baud rate detection also works with other combinations, 
such as /NOEIGHT_BIT/NOPARITY. 

Table 8-6 describes the terminal characteristic TT2$M_AUTOBAUD, which 
allows the baud rate to be set automatically at login. 

Specifying the /FRAME qualifier with the SET TERMINAL command is not 
usually recommended. The terminal driver selects the frame size (the number 
of data bits that the device can transmit) based on how the /PARITY and 
/EIGHT-BIT qualifiers are set. It might be necessary to change these values 
if the terminal is a non-DIGITAL device. 


8.2.6 Out-of-Band Control Character Handling 

All control characters (0 through IF hexadecimal) can be enabled as out- 
of-band characters. Typing one of these characters immediately delivers an 
AST to the requesting process. DCL uses this mechanism to sense whether 
CTRL/T has been entered. Out-of-band character options allow using the 
IO$M_INCLUDE function modifier to include the character in the data 
stream and the IO$M_TT_ABORT function modifier to abort the current 
input or output operation. 


8.3 Device Information 

You can obtain information on terminal characteristics by using the Get 
Device/Volume Information ($GETDVI) system service. (See the VMS System 
Services Reference Manual). The sense mode function provides an alternative 
means to obtain terminal characteristics; see Section 8.4.5. 

$GETDVI returns terminal characteristics when you specify the item codes 
DVI$_DEVCHAR, DVI$_DEVDEPEND, and DVI$_DEVDEPEND2. Tables 
g-4, 8-5 and 8-6 list these characteristics. Terminal characteristics are 
normally set during system generation to any one of, or a combination of, the 
values listed in Table 8-5. DVI$_DEVDEPEND returns a longword field in 
which the three low-order bytes contain the device-dependent characteristics 
and the high-order byte contains the page length. Page length can have 
a value in the range of 0 through 255. The $DEVDEF macro defines the 
device-independent characteristics, the $TTDEF macro defines the device¬ 
dependent characteristics, and the $TT2DEF macro defines the extended 
device-dependent characteristics. 

DVI$_DEVCLASS and DVI$_DEVTYPE return the device class and device 
type names, which are defined by the $DCDEF and $TTDEF macros, 
respectively. The device class for terminals is DC$_TERM. The terminal 
model determines the device type. For example, the device type for the 
VT240 is TT$_VT200_SERIES. DVI$_DEVBUFSIZ returns the page width. 
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which can be a value in the range of 1 through 511. The driver does not 
accept a value of 0. 

Table 8-4 Terminal Device-Independent Characteristics 


Characteristic 

Meaning 

DEV$M_AVL 

DEV$M_CCL 

DEV$M_DET 

DEV$M_IDV 

DEV$M_ODV 

DEV$M_OPR 

DEV$M_REC 

DEV$M_RTT 

DEV$M_SPL 

DEV$M_TRM 

DEV$M_NET 

Terminal is on line and available. 

Carriage control is enabled. 

Terminal is detached. 

Terminal is capable of input. 

Terminal is capable of output. 

Terminal is enabled as an operator console. 

Device is record-oriented. 

Terminal has remote terminal UCB extension. 

Device is spooled. 

Device is a terminal. 

Terminal line is allocated for VAX-DECnet use 


Table 8—5 Terminal Characteristics 


Value 1 

Meaning 

TT$M_CRFILL 

Terminal requires fill after the RETURN key is pressed (the 
fill type can be specified by the set mode function P4 
argument). 

TT$M_EIGHTBIT 

Terminal uses the eight-bit ASCII character set (see 
Appendix B). Terminals without this characteristic use 
the seven-bit ASCII code. In this case, the eighth bit is 
masked out on received characters and is ignored on 
output characters. The eighth bit is meaningful only if 
TT$M_EIGHTBIT is set. 

TT$M-ESCAPE 

Terminal generates escape sequences (see 

Section 8.2.1.4). Escape sequences are validated for 
syntax. 

TT$M_HALFDUP 

Terminal is in half-duplex mode (see Section 8.2.2.1). All 
read and write requests are executed sequentially. 

TT$M_HOSTSYNC 

The host system is synchronized to the terminal. CTRL/Q 
and CTRL/S are used to control data flow and thus keep 
the type-ahead buffer from filling. TT$M_HOSTSYNC 
should always be set on LAT terminals. 

TT$M_LFFILL 

Terminal requires fill after the line-feed character is 
processed. (The fill can be specified by the set mode P4 
argument.) 


1 Defined by the STTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit 
mask whose bit corresponds to the specific field; TT$V_ is a bit number. 
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Table 8-5 (Cont.) 

Terminal Characteristics 

Value 1 

Meaning 

TT$M—LOWER 

Terminal has the lowercase character set. Unless the 
terminal is in the PASTHRU mode or IO$M_NOFORMAT 
is specified, all input and echoed lowercase characters 
(hexadecimal 61 to 7A) are converted to uppercase if 
TT$M_LOWER is not set. (The character ALTMODE 
(decimal 125 and 126, or hexadecimal 7D and 7E) 
converts to ESCAPE on terminals that do not have the 
lowercase characteristic TT$M_LOWER set.) 

TT$M_MBXDSABL 

Mailboxes associated with the terminal do not receive 
notification of unsolicited input or hangup (see 

Section 8.2.3). This bit can be set by the IO$M_ 
DSABLMBX function modifier for read requests and 
cleared by the IO$M_ENABLMBX function modifier for 
write requests. 

TT$M_MECHFORM 

Terminal has mechanical form feed. The terminal driver 
passes form feeds directly to the terminal instead of 
expanding to line feeds. 

TT$M_MECHT AB 

Terminal has mechanical tabs and is capable of tab 
expansion. To accomplish correct line wrapping, the 
terminal driver assumes there are eight spaces between 
tab stops. 

TT$M-MODEM 

Terminal line is connected to a modem. If TT$M_ 
MODEM is set, the terminal driver automatically handles 
modem control. If TT$M_MODEM is not set, all modem 
signals are ignored. If TT$M_MODEM is set and then 
cleared, a hangup is declared on the terminal line if that 
line is in the remote state (TT$M_REMOTE is set). If 

DTR and RTS are set with IO$_SETMODE!IO$M_SET_ 
MODEM!IO$M_MAINT on a nonmodem port, DTR and 
RTS goes off and then back on when the port is set for 
modem. 

TT$M_MODEM is not supported for LAT devices. 

TT$M_NOBRDCST 

TT$M-NOECHO 

Terminal does not receive any broadcast messages. 

Input characters are not echoed on this terminal line (see 
Section 8.2.1.5). 


TT$M_NOTYPEAHD Data must be solicited by a read operation. Data is lost 
if received in the absence of an outstanding read request 


TT$M_READSYNC 

(if it is unsolicited data). Disables type-ahead feature 
(see Section 8.2.1.5). If this characteristic is set, login 
attempts on this line are disabled. See Section 8.2.3.1 
for information on modem signal control. 

Read synchronization is enabled. The host explicitly 
solicits all read operations by entering a CTRL/Q and 
terminates the operation by entering a CTRL/S. TT$M_ 
READSYNC is not applicable to LAT terminals. 


1 Defined by the $TTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit 
mask whose bit corresponds to the specific field; TT$V_ is a bit number. 
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Table 8-5 (Cont.) 

Terminal Characteristics 

Value 1 

Meaning 

TT$M—REMOTE 

Dial-up characteristic is enabled. The terminal returns 
to local mode when a hangup occurs on the terminal 
line (see Section 8.2.3). This characteristic cannot be 
changed; it is only informational. 

TT$M_SCOPE 

Terminal is a video screen display (CRT terminal), for 
example, the VT100 or VT240. 

TT$M_TTSYNC 

The terminal is synchronized to the host system. Output 
to the terminal is controlled by terminal-generated CTRL/Q 
and CTRL/S. TT$M_TTSYNC is not applicable to LAT 
terminals unless TT$M_PASTHRU is set and 
TT$M_TTSYNC is disabled, in which case the LAT 
session is placed in PASSALL mode. 

TT$M_WRAP 

A carriage-return/line-feed combination should be inserted 
if the cursor moves beyond the right margin. If 
TT$M_WRAP is not set, no carriage-return/line-feed 
combination is sent. The VMS operating system does not 
support hardware-provided wrapping functions. 

'Defined by the $TTDEF macro. The prefix can be TT$M_ or TT$V_. TT$M_ is a bit 
mask whose bit corresponds to the specific field; TT$V_ is a bit number. 

Table 8—6 Extended Terminal Characteristics 

Value 1 

Meaning 

TT2$M_ALTYPEAHD 

Alternate type-ahead buffer size is enabled. Use 
the alternate type-ahead buffer size specified during 
system generation (see Section 8.2.1.5). If a type- 
ahead buffer already exists for a terminal line, there 
is no effect when this characteristic is set for that 
line. TT2$M_ALTYPEAHD should be set prior to 
using the terminal, such as in the startup command 
procedure. You can only set TT2$M_ALTYPEAHD, 
this characteristic cannot be cleared until the system 
is rebooted. 

TT2$M_ANSICRT 

ANSI CRT terminal is enabled. This characteristic 
is set by the SET TERMINAL command. TT2$M_ 
ANSICRT is a subset of the ANSI standard with no 
DIGITAL-private escape sequences (see Appendix 

B). It is also a subset of the VT 100-family terminals 
(because TT2$M_ANSICRT is a subset of TT2$M_ 
DECCRT) and the VT100. Terminals with this 
characteristic must provide a display of at least 24 
lines, each with 80 columns. 

TT2$M_APP_KEYPAD 

Notifies application programs of state to set the 
keypad to when exiting. 


'Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a 
bit mask in which the bit set corresponds to the specific field; TT2$V_ is a bit number. 
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Table 8-6 (Cont.) Extended Terminal Characteristics 


Value 1 

Meaning 

TT2$M_AUTOBAUD 

Automatic baud rate detection is enabled. This 
characteristic allows the baud rate to be set 
automatically when you log in. (The baud rate is 
set when one or more carriage returns are entered 
during the login procedure.) Terminals are set to 
a permanent speed of 9600 baud. If TT2$M_ 
AUTOBAUD is specified, the permanent speed 
must not be changed while this characteristic is 
in use on a given terminal line. See Section 8.2.5 
for additional information on automatic baud rate 
detection. 

TT2$M_AVO 

Advanced video is enabled. This characteristic 
provides the terminal with blink, bold, and flashing 
fields as well as a full screen of 132 character 
lines. TT2$M_AVO is set by the SET TERMINAL 
command. Appendix B lists the valid escape 
sequences for terminals with the TT2$M_AVO 
characteristic. 

TT2$M-BLOCK 

Block mode is enabled. This characteristic is set 
by the SET TERMINAL command. TT2$M_BLOCK 
defines additional ANSI-defined and DIGITAL-private 
escape sequences (see Appendix B). Terminals with 
this characteristic are capable of local editing and 
block mode transmission (XON/XOFF flow control 
must be honored), and have protected fields. If the 
terminal is used for large amounts of block input, 
TT2$M_ALTYPEAHD should also be specified. 

TT2$M_BRDCSTMBX 

Mailbox broadcasts messages. Broadcast messages 
are sent to an associated mailbox, if one exists. 

TT2$M_DECCRT 

DIGITAL CRT terminal. This characteristic is set 
by the SET TERMINAL command for all terminals 
that are upward-compatible with VT 100-family 
terminals. TT2$M_DECCRT is a superset of 
TT2$M_ANSICRT. Additional ANSI-defined as 
well as most DIGIT AL-private escape sequences are 
allowed for terminals with this characteristic (see 
Appendix B); maintenance modes, VT52 mode, 
and the use of the LED displays are not defined by 
TT2$M_DECCRT. Not all VT 100-family terminals 
implement these features. The presence of the 
advanced video feature cannot be assumed because 
it is a VT100 option. This restricts the use of 
graphics attributes. However, the TT2$M_AVO 
characteristic can be used to determine whether 
additional graphic attributes are available. 


1 Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a 
bit mask in which the bit set corresponds to the specific field; TT2$V_ is a bit number. 
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Table 8-6 (Cont.) Extended Terminal Characteristics 


Value 1 

Meaning 

TT2$M_DECCRT2 

DIGITAL CRT terminal. This characteristic is set 
by the SET TERMINAL command for all terminals 
that are upward-compatible with VT200-family 
terminals. TT2$M_DECCRT2 is a superset of 
TT2$M_DECCRT. 

TT2$M_DIALUP 

Terminal is a dial-up line. Used by LOGINOUT for 
the disable dial-up control. 

TT2$M_DISCONNECT 

Allows terminal disconnect when a hangup occurs 
(that is, when modem signals are lost, when 
the DCL commands DISCONNECT, or CONNECT 
/CONTINUE are entered, or when the BREAK key 
is pressed on a terminal that has the TT2$M_ 
SECURE characteristic). These terminals are 
created as VTAn:. (See the description for the 

DCL command CONNECT/DISCONNECT in the VMS 
DCL Dictionary). 

TT2$M_DMA 

DMA mode. This characteristic enables the use of 
DMA mode for asynchronous DMA multiplexers. It 
is ignored by non-DMA controllers. 

TT2$M_DRCS 

Terminal supports loadable character fonts. This 
characteristic is set with the DCL command SET 
TERMINAL/SOFT_CHARACTERS. 

TT2$M_EDIT 

Terminal edit. This characteristic is set by the SET 
TERMINAL command for all terminals that support 
ANSI-defined advanced editing functions. These 
functions include the ability to insert or delete a line 
and the ability to insert or delete characters in an 
existing line. Terminals with this characteristic are 
a superset of TT2$M_DECCRT. Appendix B lists 
the valid escape sequences for terminals with the 
TT2$M_EDIT characteristic. 

TT2$M_EDITING 

Line editing is allowed. 

TT2$M_FALLBACK 2 

Output is transformed from the eight-bit 
multinational character set to a seven-bit ASCII 
character set on terminals that do not support the 
eight-bit character set (see Appendix B). 

TT2$M_HANGUP 

Terminal hangup. Terminal lines connected through 
modems are hung up when a process logs out or is 
deleted. The state of this characteristic cannot be 
changed unless TT2$M_MODHANGUP is enabled or 
the process has either LOG_IO or PHY_IO privilege. 

TT2$M_INSERT 

Sets default mode for insert or overstrike at the 
beginning of each read operation. 


1 Defined by the $TT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a 
bit mask in which the bit set corresponds to the specific field; TT2$V_ is a bit number. 

2 If an attempt is made to turn on TT2$V_FALLBACK for a disconnected virtual terminal 
(—VTAx:) or if the Terminal Fallback Facility (TFF) has not been activated, the status code 
SS$_BADPARAM is returned. For more information on TFF, refer to the VMS Terminal 
Fallback Utility Manual. 
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Table 8-6 (Cont.) Extended Terminal Characteristics 


Value 1 

Meaning 

TT2$M_LOCALECHO 

Local echo. This characteristic is used with 

TT$M_NOECHO. If both characteristics are set, 
only terminators and special control characters are 
echoed. Use of this mode is restricted to command 
line read operations. Application programs that 
use the IO$M_NOECHO function modifier will not 
necessarily work if TT2$M_LOCALECHO is set. 

Local echo is also not compatible with line editing 
(TT2$M_EDITING). 

TT2$M_MODHANGUP 

Modify hangup. If specified, TT2$M_HANGUP can 
be modified without privilege. Otherwise, logical or 
physical I/O privilege is required. 

TT2$M_PASTHRU 

Terminal is in PASTHRU mode; all input and output 
data is in seven- or eight-bit binary format (no data 
interpretation occurs). Data is terminated when the 
buffer is full or when the data that is read matches 
the specified terminator. If the characteristic 
TT$M_TTSYNC is set, CTRL/S and CTRL/Q 
interpretation does occur. 

TT2$M_PRINTER 

DIGITAL CRT terminal with a local printer port. 

TT2$M_REGIS 

ReGIS graphics. The terminal supports the ReGIS 
graphics instruction set. 

TT2$M_SIXEL 

SIXEL graphics. The terminal supports the SIXEL 
graphics instruction set. 

TT2$M_SECURE 

For use with nonmodem, nonautobaud lines. 

This characteristic guarantees that no process is 
connected to the terminal after the BREAK key is 
pressed. If TT2$M-SECURE is not set, BREAK is a 
null key. 

TT2$M_SETSPEED 

Set speed. If specified, either LOG—IO or 

PHY—10 privilege is required to change terminal 
speed. TT2$M_SETSPEED is not supported for 

LAT devices. 

TT2$M_SYSPWD 

System password. This characteristic specifies 
that the login procedure should require the system 
password before the user name prompt is displayed. 

TT2$M_X0N 

XON/XOFF control. If a set mode function is 
performed on a terminal in the CTRL/S state, and 
if TT2$M_XON is set, output is resumed. Users 
should note that the driver will attempt to resume 
stopped (XOFF) output on the line. However, 
restarting the output may not be successful in all 
cases. The XON/XOFF feature does not work on all 
terminals, for example, the VT220. 

'Defined bv the STT2DEF MACRO. The prefix can be TT2$M_ or TT2$V_. TT2$M_ is a 

bit mask in which the bit set 

corresponds to the specific field; TT2$V_ is a bit number. 
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8.3.1 Terminal Characteristics Categories 

The set mode and set characteristics functions (see Section 8.4.3) and the DCL 
command SET TERMINAL are used to change terminal characteristics. The 
VMS DCL Dictionary describes the SET TERMINAL command. 

To customize terminal behavior and usage, the VMS operating system divides 
terminal characteristics into the following categories: 

• Format effectors—The following characteristics allow the user to specify 
terminal-dependent formatting requirements: 

TT$M_CRFILL TT$M_EIGHTBIT TT$M_LFFILL 

TT$M_LOWER TT2$M_LOCALECHO TT$M_MECHFORM 

TT$M_MECHTAB TT$M_NOECHO TT$M_SCOPE 

TT$M_WRAP 

* Generic terminal capabilities—The following characteristics specify 
generic terminal features available to applications programs: 

TT2$M_ANSICRT TT2$M_AVO TT2$M_BLOCK 

TT2$M_DECCRT TT2$M_DECCRT2 TT2$M_DRCS 

TT2$M_EDIT TT2$M_PRINTER TT2$M_REGIS 

TT2$M_SIXEL 


Their use allows execution of these programs without knowledge of the 
actual terminal type. For example, a program should check for 
TT2$M_DECCRT rather than for VT100 or VT101. 

• Protocol—The following characteristics control protocols used by the 

terminal: 

TT$M_ESCAPE TT$M_HALFDUP TT$M_HOSTSYNC 

TT2$M_PASTHRU TT$M_TTSYNC 








System management—The following characteristics, normally set only at 
system startup, allow the system manager to regulate terminal usage: 


TT2$M_ALTYPEAHD 

TT2$M_DISCONNECT 

TT$M_MODEM 

TT2$M_SECURE 


TT2$M_AUTOBAUD 

TT2$M_DMA 

TT$M_NOTYPEAHD 

TT2$M_SETSPEED 


TT2$M_DIALUP 

TT2$M_HANGUP 

TT2$M_MODHANGUP 

TT2$M_SYSPWD 


User preference—The following characteristics allow you to customize the 
terminal operating mode: 


TT2$M_APP_KEYPAD TT2$M_FALLBACK TT2$M_EDITING 
TT2$M_INSERT TT$M_NOBRDCST 


Miscellaneous The following characteristics provide greater program 
control of terminal operations: 

TT2$M_BRDCSTMBX TT$M_MBXDSABL TT2$M_XON 
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8.4 Terminal Function Codes 

The basic terminal I/O functions are read, write, set mode, set characteristics, 
sense mode, and sense characteristics. All I/O functions can take function 
modifiers. 


8.4.1 Read 

When a read function code is issued, the user-specified buffer is filled with 
characters from the associated terminal. The VMS operating system provides 
the following read function codes: 

• IO$_READVBLK—Read virtual block 

• IO$_READLBLK—Read logical block 

• IO$_READPROMPT—Read with prompt 

Read operations are terminated if either of the following two conditions 
occurs: 

• The user buffer is full. 

• The received character is included in a specified terminator mask (see 
Section 8.4.1.2). 

The following device- or function-dependent arguments are used with the 
read function codes. The codes can take all six arguments (PI through P6) on 
QIO requests. The descriptions for these arguments differ when itemlist read 
operations are performed (see Section 8.4.1.3). 

• pi—The starting virtual address of the buffer that is to receive the data 
read. 

• p2—The size of the buffer that is to receive the data read in bytes. (A 
system generation parameter, MAXBUF, limits the maximum size of the 
buffer.) 

• p 3 —R ea d with timeout, timeout count (see Table 8-7, IO$M_TIMED). 

• p 4 _The read terminator descriptor block address (see Section 8.4.1.2). 

• p 5 _The starting virtual address of the prompt buffer that is to be written 

to the terminal; for read with prompt operations using the 
IO$_READPROMPT function code. (This argument is specified as a 
value, rather than an address as in the PI argument.) 

• P6—The size of the prompt buffer that is to be written to the terminal; 
for read with prompt operations using the IO$_READPROMPT function 
code. 

In a read with prompt operation, the P5 and P6 arguments specify the 
address and size of a prompt string buffer containing data to be written to 
the terminal before the input data is read. In a read with prompt operation, 
both read and write operations are performed on the specified terminal. The 
prompt string buffer is formatted like'any other write buffer. If cursor position 
specifiers are supplied, they are not interpreted by the driver but passed to 
the terminal. 
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During a read with prompt operation, pressing CTRL/O (which is turned off 
at the start of any read operation) stops the prompt string. If you press either 
CTRL/U or CTRL/X, the entire prompt string is written out again, and the 
current input is ignored. If you press CTRL/R, the current prompt string and 
input are written to the terminal. 

Depending on the terminal type and your input, the prompt string can be 
very simple or quite complex—from single command prompts to screen fills 
followed by input data. DIGITAL recommends that prompt strings contain 
only one leading line feed. 

In PASTHRU mode, data received from the associated terminal is placed in 
the user buffer as binary information without interpretation. (Prompts are not 
refreshed after a broadcast in PASTHRU mode.) 


Function Modifier Codes for Read QIO Functions 

Eight function modifiers can be specified with IO$_READVBLK, 
IO$_READLBLK, and 10$—READPROMPT. Table 8—7 lists these function 
modifiers and IO$_EXTEND, which is described in 8.4.1.3. All read function 
modifiers are supported for LAT devices. 

Table 8-7 Read QIO Fun ction Modifiers for the Terminal Driver 

Code Consequence 


Lowercase alphabetic characters (hexadecimal 61 to 7A) 
are converted to uppercase when transferred to the user 
buffer or echoed. This characteristic is used only for I0$_ 
READLBLK, IO$_READVBLK, and IO$_READPROMPT. 

The mailbox is disabled for unsolicited data. 

A valid ANSI escape sequence is recognized as a valid 
delimiter for the read operation. The TT$M_ESCAPE 
characteristic is overridden by this modifier for the current 
read operation. 

This characteristic provides additional functionality for 
read operations (see Section 8.4.1.3). Do not specify 
IO$M_EXTEND with other function modifiers. 

Characters are not echoed as they are entered at the 
keyboard. The terminal line can also be set to a “no 
echo” mode by the set mode characteristic TT$M_ 
NOECHO, which inhibits all read operation echoing. 

Setting IO$M_NOECHO also disables line editing. 

The terminal does not interpret CTRL/U, CTRL/R, or DEL. 
They are passed to the user. IO$M_NOFILTR explicitly 
disables line editing. 

The type-ahead buffer is purged before the read operation 
begins. 


IO$M_CVTLOW 

IO$M_DSABLMBX 

IO$M_ESCAPE 

IO$M_EXTEND 

IO$M_NOECHO 

IO$M_NOFILTR 

IO$M_PURGE 
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Table 8-7 (Cont.) 

Read QIO Function Modifiers for the Terminal 
Driver 

Code 

Consequence 

IO$M_TIMED 

The P3 argument specifies the maximum time (seconds) 

that can elapse between characters received from the 
terminal (the timeout value for the operation). Because 
driver timing operates on a one-second timer, a two- 
second timeout must be specified to guarantee a one- 
second wait. The timer starts when the prompt echo is 
started. If the read time exceeds the time specified in 

P3 / a timeout error (SS$_TIMEOUT) is returned in the 
read IOSB. All input characters received before the read 
operation timed out are returned in the user's buffer. 


A read with timeout operation, in which the timeout value 
is 0, empties the type-ahead buffer into the user buffer 
until the proper termination condition is reached (buffer 
full, termination character detected, or type-ahead buffer 
empty). The read operation then returns the count of 
characters read and, if a terminator is read, 

SS$_NORMAL; SS$_TIMEOUT is returned if no 
terminator is read. In either case the offset to terminator 
in the IOSB always indicates the number of characters 
read. Note that the timer starts when the prompt echo is 
started. 

IO$M —TRMNOECHO 

If a read operation is interrupted by either a broadcast 
write or a synchronous write request, the timer operation 
is restarted. 

The termination character (if any) is not echoed. There 
is no formal terminator if the buffer is filled before the 
terminator is typed. 


8.4.1.2 


Read Function Terminators 

The P4 argument to a read QIO function either specifies the terminator set 
for the read function or points to the location containing the terminator 
set If P4 is 0, all ASCII characters with a code in the range 0 through 31 
(hexadecimal 0 through IF) except LF, VT, FF, TAB, and BS, are terminators 
see Appendix B). This is the VMS RMS standard terminator set. The delete 
character (hexidecimal 7F) and eight-bit controls in the range 128 through 
159 and 255 (hexidecimal 80 through 9F, and FF) are also terminators. If line 
editing is enabled, only RETURN, CTRL/Z, or an escape sequence terminates 
a read operation. 


If P4 does not equal 0, it contains the address of a quadword that either 
specifies a terminator character bit mask or points to a location containing 
that mask. (Note that if P4 references an address in a MACRO program, 
a number sign (#) must precede the address, for example, P4=#TMASK.) 
The quadword has a short form and a long form, as shown in Figure 8-3. 

In the short form, the correspondence is between the bit number and the 
binary value of the character; the character is a terminator if the bit is set. 
For example, if bit 0 is set, NULL is a terminator; if bit 9 is set, TAB is a 
terminator. If a character is not specified, it is not a terminator. Since ASCII 
control characters are in the range 0 through 31, the short form can be used 
in most cases. 


8-29 














Terminal Driver 

8.4 Terminal Function Codes 


The long form allows use of a more comprehensive set of terminator 
characters. Any mask equal to or greater than one byte is acceptable. For 
example, a mask size of 16 bytes allows all seven-bit ASCII characters to be 
used as terminators; a mask size of 32 bytes allows all eight-bit characters to 
be used as terminators for eight-bit terminals. 

If the terminator mask is all zeros, there are no specified terminators. The 
read operation ends when the specified number of bytes (characters) have 
been transferred to the input buffer. 

Certain control keys will not act as terminators unless IO$M_NOFILTR 
is specified or the line has the TT2$M_PASTHRU characteristic (see 
Section 8.2.1.2.). v 

Figure 8-3 Short and Long Forms of Terminator Mask Quadwords 


SHORT: 


31 


0 


terminator character bit mask 


LONG: 


31 


16 15 


(not used) 


mask size in bytes 


address of mask 
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8.4.1.3 Itemlist Read Operations 

Itemlist read operations provide expanded software features to read QIO 
requests. The VMS operating system provides the following combination of 
function code and modifier: 

• 10$—READVBLK!IO$M—EXTEND—Itemlist read virtual block 

No other function modifiers can be specified in an itemlist read request. 

Note: Itemlist read features supported by the terminal driver are not supported 
by all DECNET terminal emulators. VV 

The itemlist read function code and modifier combination takes the following 
device- or function-dependent arguments: 6 

• PI—The starting virtual address of the buffer that is to receive the data 
read 

• P2—The size of the buffer that is to receive the data read in bytes. If 
required, the P2 size includes additional space for an overflow buffer to 
hold an escape sequence terminator (see item code TRM$_ESCTRMOVR 
in Table 8-8). 
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• p 3 —The access mode at which the itemlist is to be probed (optional) 

• ps—The address of the itemlist buffer 

• p6—The length in bytes of the itemlist buffer 

P4 is not meaningful for itemlist read operations. P5 points to a series of item 
descriptors. Figure 8-4 shows the format for these descnptors. You cannot 
repeat the same item code in the same item list. 

Figure 8-4 Itemlist Read Descriptor 


31 


16 15 


item code 


buffer length 


buffer address or immediate data 


return address* 


must be zero 


Itemlist Read — P5 Buffer 
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Table 8-8 lists the item codes that can be specified in the first longword of 
the item descriptors. 

Table 8-8 Item Codes for Itemlist Read Operations for the Terminal 
Driver 


Item Code_Meaning ____ 

TRM$_ALTECHSTR Alternate echo string. The buffer length word contains 
the length of the string. The data address word contains 
the address of the string. The alternate echo string is 
written to the terminal after the first character is entered. 


Note: This item code for character validating read mode 
(TRM$K_EM_RDVERIFY) editing only. 

TRM$_EDITMODE Extended editing modes. The immediate data longword 

specifies extended editing mode values. The buffer length 
word must be zero. The following editing modes are 
supported: 

TRM$K_EM_DEFAULT Normal read mode. This 

is the default if TRM$_ 
EDITMODE is not present in 
the itemlist. 

TRM$K_EM_RDVERIFY Character validating read 

mode. See Section 8.4.1.4. 
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Table 8-8 (Cont.) Item Codes for Itemlist Read Operations for the 
Terminal Driver 


Item Code 


Meaning 


TRM$ESCTRMOVR 


TRM$_FILLCHR 


Note: 


TRM$_INIOFFSET 


TRM$_INISTRNG 


Escape terminator overflow size. Specifies the number 
of bytes that may be used to hold an escape sequence 
terminator. This number should be included in P2, the 
buffer size argument, in addition to the space required for 
the data to be read. Note that this overflow area is for 
the terminator only; it is not available for user data. 

TRM$_ESCTRMOVR is useful in preventing partial 
escape errors, which return SS$_PARTESCAPE. This 
overflow buffer ensures that all the characters in an 
escape sequence terminator will fit in the user buffer, thus 
eliminating the need for additional single-character read 
operations. 

A two-byte value that indicates the fill and clear character 
for TRM$K_EM_RDVERIFY. The first byte of the 
immediate data longword specifies the clear character; the 
second byte specifies the fill character. 

This item code for character validating read mode 
(TRM$K_EM_RDVERIFY) editing only. 

Indicates the character in the initial string where echoing 
starts. The immediate data longword specifies the 
character. 

Specifies a string to preload into the read buffer (PI). 

The buffer length word contains the length of the string. 
The data longword contains the address of the string. 
TRM$_INISTRNG must be specified if the edit mode is 
TRM$K_EM_RDVERIFY, and must be the same length as 
specified by TRM$_PICSTRNG. 
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Table 8-8 (Cont.) Item Codes for Itemlist Read Operations for the 
Terminal Driver 


Item Code Meaning 


TRM$_MODIFIERS Read modifiers. The immediate data longword contains a 

32-bit value that specifies modifiers to read operations, 
which are defined in $TRMDEF. The buffer length word 
must be zero. The following bits are defined: 


TRM$M _TM _ AUT 0_T AB 

This bit creates an auto-tab 
mode field (TRM$K_EM_ 
RDVERIFY mode only). 

TRMSM _TM _C VTLO W 

Lowercase alphabetic 
characters (hexadecimal 61 
to 7A) are converted 
to uppercase when 
transferred to the user 
buffer or echoed. 

TRM$M_TM_DSABLMBX 

The mailbox is disabled for 
unsolicited data. 

TRM$M_TM_ESCAPE 

A valid ANSI escape 
sequence is recognized as 
a valid delimiter for the 
read operation. 

TRMSM _TM_NOECHO 

Characters are not echoed 
as they are entered at the 
keyboard. 

TRM$M_TM_NOEDIT 

This bit inhibits advanced 
editing for this read 
operation. 

TRM$M_TM_NOFILTR 

The terminal does not 
interpret DEL, CTRL/U, or 
CTRL/R, but passes them 
to you. This characteristic 
explicitly disables line 
editing. 
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Table 8—8 (Cont.) 

Item Codes for Itemlist Read Operations for the 
Terminal Driver 

Item Code 

Meaning 



TRM$M_TM_NORECALL 

This bit inhibits command 
recall (CTRL/B) by the 
terminal driver. 


TRM$M_TM_PURGE 

The type-ahead buffer is 
purged before the read 
operation begins. 


TRM$M_TM_R_JUST 

This bit creates a right- 
justified field (TRM$K_ 
EM_RDVERIFY mode 
only). 


TRM$M_TM—TIMED 

TRM$_TIMEOUT specifies 
the maximum time 
(seconds) that can elapse 
between characters 
received from the terminal; 
that is # the timeout 
value for the operation. 
TRM$M_TM_TIMED is 
assumed set if TRM$_ 
TIMEOUT is included in the 
itemlist. 


TRM$M_TM_TRMNOECHO 

The termination character 
(if any) is not echoed. 

There is no formal 
terminator if the buffer is 
filled before the terminator 
is typed. 


Note: All other bits must be zero, 
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Table 8—8 (Cont.) Item Codes for Itemlist Read Operations for the 
Terminal Driver 


Item C ode _ Meaning ___ 

TRM$_PICSTRNG Character validation string. The buffer length word 

contains the length of the string, which must be the 
same as the length specified by TRM$_INISTRNG. The 
data address word contains the address of the string. 
TRM$_PICSTRNG must be specified if the edit mode is 
TRM$K_EM_RDVERIFY. 

Note: This item code for character validating read mode 
(TRM$K_EM_RDVERIFY) editing only. 

The format of the character validation string is one 
byte per input character. Each byte is a bit mask. The 
following values are provided: 


Value 

Meaning 

TRM$M_CV_UPPER 

Uppercase alphabetic 

TRM$M_CV_LOWER 

Lowercase alphabetic 

TRM$M_CV_NUMERIC 

Numeric (0 - 9) 

TRM$M CV NUMPUNC 

Numeric punctuation (+ - .) 

TRM$M_CV_PRINT ABLE 

Printable ASCII character 

TRM$M_CV_ANY 

Any character 


If no values are set, the corresponding character specified 
by TRM$_INISTRNG is used. Appendix B lists the 
multinational character set. 


TRM$_PROMPT Specifies a prompt string. The buffer length word 

contains the length of the prompt. The data address 
word contains the address of the prompt string. See 
Section 8.4.1 for information on how carriage control 
specifiers in a prompt string are handled. 

TRM$_TERM The buffer length word determines the format of the 

nondefault terminator mask. If the buffer length word 
is zero, then the data longword is used as a short form 
mask. If the buffer length word is nonzero, then a mask n 
bytes long is available at the specified address. 

TRM$_TIMEOUT Read timeout. See the description of IO$M_TIMED in 
Table 8-7. 


8.4.1.4 Read Verify Function 

When using the read verify function, the terminal driver performs input 
validation based on character attributes. 1 Validation is performed one 
character at a time as data is entered. Invalid characters are not echoed, 
and cause the read operation to complete. It is then up to the application 
program to handle the error appropriately. 



Read verification bypasses the optionally specified termination mask (TRM$_TERM). 
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The initial string describes the initial contents of the input field. This string 
may consist of data and marker characters. The clear character is displayed 
on the screen for each occurrence of the fill character in the initial string 
buffer. 6 

The picture string is a string of bytes where each byte corresponds to one 
character of the field being entered. Each byte specifies a mask of legal 
character types for that character position. If the byte is left as zero, then 
that position is a marker character, and the character from the initial string is 
echoed for that position. 

For left-justified fields, the prompt data is output to the terminal, followed bv 
an optional number (TRM$_INIOFFSET) of initial string characters. Leading 
maricer characters are always output following the prompt, leaving the cursor 
at the leftmost data position. As each character is entered, it is validated and 
then echoed advancing the cursor position. Additional marker characters are 
skipped as they are encountered. If an input character fails the validation, the 
read operation is completed with the invalid character as the terminator. 

For right-justified fields, the prompt is output and is followed by the initial 
string. (In general, TRM$_INIOFFSET is set to the length of 
TRM$_INISTRNG for right-justified fields.) The cursor position remains one 
position to the right of the initial string. For proper operation, right-justified 
fields cannot have mixed picture definitions. After each character is input 
the entire prompt and input fields are output. Therefore, the prompt should 
include a cursor positioning escape sequence. 

The definition of full field is different for left- and right-justified read 
operations. For left-justified fields, full field is detected when the character 
corresponding to the last nonmarker position in the picture string has been 
entered. For right-justified fields, full field is detected when a character other 
field ™ character is shifted into the leftmost, nonmarker position in the 

If the modifier TRM$M_TM_AUTO_TAB is set in TRM$_MODIFIERS then 
detection of a full field terminates the read operation. In the event of autotab 
termination, the terminator character in the IOSB is null. If the autotab 
option is not selected, then termination occurs when one more character 
is typed to a full field. Applications can detect this condition when the 
terminating character index is one character beyond the end of the field. The 
extra character is reported as the terminator. In a left-justified field the ioSB 
index to the terminator is zero-based; in a right-justified field this index is 
one-based. 

If a read verify function is interrupted by an asychronous write operation, the 
read verify is completed with status SS$_OPINCOMPL. 

No line editing functions other than the delete character function are 
supported for read verify. 
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8.4.2 Write 


8.4.2.1 


Write operations display the contents of a user-specified buffer on the 
associated terminal. The VMS operating system provides the following 
write I/O functions, which are listed with their function codes: 

• IO$_WRITEVBLK—Write virtual block 

• IO$_WRITELBLK—Write logical block 

• IO$_WRITEPBLK—Write physical block 


The write function codes can take the following device- or function-dependent 
arguments: 

• pi_The starting virtual address of the buffer that is to be written to the 

terminal 

• P2—The number of bytes that are to be written to the terminal (A system 
generation parameter, MAXBUF, limits the maximum size of the buffer.) 

• p 4 —carriage control specifier except for write physical block operations 
(Write function carriage control is described in Section 8.4.2.2.) 


P3, ps, and P6 are not meaningful for terminal write operations. 


In write virtual block and write logical block operations, the buffer (PI and 
P2) is formatted for the selected terminal and includes the carriage control 
information specified by P4. 


Unless TT$M _MECHFORM is specified, multiple line feeds are generated for 
form feeds. The number of line feeds generated depends on the current page 
position and the length of the page. By producing a carriage return after the 
last line feed, a form feed also moves the cursor to the left margin. Multiple 
spaces are generated for tabs if the characteristics of the selected terminal do 
not include TT$M —MECHTAB (this does not apply to wnte physical block 
operations). Tab stops occur every eight characters or positions. 


Function Modifier Codes for Write QIO Functions 

Five function modifiers can be specified with IO$_WRITEVBLK, 
IO$_WRITELBLK, and IO$_WRITEPBLK. Table 8-9 lists these function 
modifiers. All write function modifiers are supported for LAT devices. 


Table 8—9 Write QIO Function Modifiers for the Terminal Driver 


Code 

IO$M _BRE AKTHRU 
IO$M _C ANCTRLO 
IO$M_ENABLMBX 


Consequence__ 

Allows breakthrough read regardless of the current active 
state. 

Turns off CTRL/O (if it is in effect) before the write 
operation. Otherwise, the data cannot be displayed. 

Enables use of the mailbox associated with the terminal 
for notification that unsolicited data is available. 


IO$M_NOFORMAT Allows you to specify write functions without 

interpretation or format; in effect, the terminal line is 
in a temporary PASTHRU mode. 
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Table 8-9 (Cont.) 


Write QIO Function Modifiers for the Terminal 
Driver 


Code 


Consequence 


IO$M REFRESH 


If a read operation is interrupted by a write operation (by 
either a write breakthrough'or any other type of write), 
the terminal displays the current read data when the read 
function is restarted. 


'Any interruption caused by the execution of the $BRDCST or the SBRKTHRU system 

service broadcasting messages to terminals is referred to as a 'write breakthrough." 


8.4.2.2 Write Function Carriage Control 

The P4 argument is a longword that specifies carriage control. Carriage 
control determines the next printing position on the terminal. P4 is ignored in 
a wnte physical block operation. Figure 8-5 shows the P4 longword format. 

Only bytes 0, 2, and 3 in the longword are used. Byte 1 is ignored. If the 
low-order byte (byte 0) is not 0, the contents of the longword are interpreted 
as a FORTRAN carriage control specifier. Table 8-10 lists the possible byte 0 
values (in hexadecimal) and their meanings. 

Figure 8-5 P4 Carriage Control Specifier 



3 

2 

1 

0 

P4: 

POSTFIX 

PREFIX 

(not used) 

FORTRAN 
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Table 8-10 Write Function Carriage Control (FORTRAN: byte 0 not 


equal to 0) 


Byte 0 Value 
(hexadecimal) 

ASCII 

Character 

Meaning 

20 

(space) 

Single-space carriage control. (Sequence: 
carriage-return/line-feed combination, print 
buffer contents, return 1 ) 

30 

0 

Double-space carriage control. (Sequence: 
carriage-return/line-feed combination, 
carriage-return/line-feed combination, print 
buffer contents, return 1 ) 

31 

1 

Page eject carriage control. (Sequence: form 
feed, print buffer contents, return) 

2B 

+ 

Overprint carriage control; allows double 
printing for emphasis or special effects. 
(Sequence: print buffer contents, return) 

24 

$ 

Prompt carriage control. (Sequence: 
carriage-return/line-feed combination, print 
buffer contents) 

All other 
values 


Same as ASCII space character: 
single-space carriage control 

’A carriage-return/line-feed combination is a carriage return followed by a line feed. 


If the low-order byte (byte 0) is 0, bytes 2 and 3 of the P4 longword are 
interpreted as the prefix and postfix carriage control specifiers. The prefix 
(byte 2) specifies the carriage control before the buffer contents are printed. 
The postfix (byte 3) specifies the carriage control after the buffer contents are 
printed. The sequence is as follows: 

1 Prefix carriage control 

2 Print 

3 Postfix carriage control 

The prefix and postfix bytes, although interpreted separately, use the same 
encoding scheme. Table 8-11 shows this encoding scheme in hexadecimal. 

With several exceptions. Figure 8-6 shows the prefix and postfix hexadecimal 
coding that produces the carriage control functions listed in Table 8-10. Prefix 
and postfix coding provides an alternative way to achieve these controls. 

In the first example in Figure 8-6, the prefix/postfix hexadecimal coding for 
a single-space carriage control (carriage-retum/line-feed combination, print 
buffer contents, return) is obtained by placing the value 1 in the second 
(prefix) byte and the sum of the bit 7 value (80) and the return value (D) in 
the third postfix byte. 

80 (bit 7=1) 

+ D (return) 

8D (postfix = return) 
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Table 8-11 Write Function Carriage Control (P4 byte 0 = 0) 

Prefix/Postfix Bytes (Hexadecimal) 


Bit 7 

Bits 

0-6 

Meaning 

0 

0 

No carriage control is specified (NULL). 

0 

1-7F 

Bits 0 through 6 are a count of 
carriage-return/line-feed combinations. 

Bit 7 Bit 6 

Bit 5 

Bits 0-4 Meaning 

1 0 

0 

1-1F Output the single ASCII control 

character specified by the 
configuration of bits 0 through 4 
(seven-bit character set). 

1 1 

0 

1-1F Output the single ASCII control 

character specified by the 
configuration of bits 0 through 

4, which are translated as ASCII 
characters 128 through 159 (eight-bit 
character set; see Appendix B). 


8.4.3 Set Mode 

Set mode operations affect the operation and characteristics of the associated 
terminal line. The VMS operating system provides two types of set mode 
functions: set mode and set characteristics. 

The set mode function affects the mode and temporary characteristics of the 
associated terminal line. Set mode is a logical I/O function and requires no 
privilege. 1 The following function code is provided: 

• IO$_SETMODE 

The set characteristics function affects the permanent characteristics of the 
associated terminal line. Set characteristics is a physical I/O function and 
requires the privilege necessary to perform physical I/O. The following 
function code is provided: 6 

• IO$_SETCHAR 


M' aVC ?? u" PHY -j° P rivile g e ' the terminal driver does not accept a set mode request to a 
* d ^ CS n0t , haV ® the . extended terminal characteristic TT2$M_SETSPEED—even if no request for a 
spe^d is made “ ' Pnvlle S e 18 not rec l uired if TT2$M_SETSPEED is set but no attempt to change the 
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Figure 8-6 Write Function Carriage Control (Prefix and Postfix 
Coding) 


(Space) 


8D 

1 

- 

0 

"0“ 



8D 

2 

- 

0 

"1" 



8D 

8C 

- 

0 




8D 

0 

- 

0 




0 

1 

- 

0 

Example: Skip ! 

24 lines before printing 


8D 

18 

- 

0 


Sequence: 

Prefix = NL 
Print 

Postfix = CR 


Sequence: 

Prefix = NL, NL 
Print 

Postfix = CR 


Sequence: 

Prefix = FF 
Print 

Postfix = CR 


Sequence: 

Prefix = NULL 
Print 

Postfix = CR 


Sequence: 

Prefix = NL 
Print 

Postfix = NULL 


Sequence: 

Prefix = 24NL 
Print 

Postfix := CR 

ZK-665-82 


The set mode and set characteristics functions take the following device- or 
function-dependent arguments if no function modifiers are specified. 

• pi—Address of characteristics buffer 

• p2—Length of characteristics buffer (default length is 8 bytes) 

. p 3 —Speed specifier (bits 0 through 7 = transmit; 8 through 15 = receive) 

• p 4 —pi)) specifier (bits 0 through 7 = CR fill count; bits 8 through 15 - LF 
fill count) 

• P5—Parity flags 
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Figure 8-7 Set Mode and Set Characteristics Buffers 


24 23 16 15 


page 

width 

type 

' u 

class 

page 
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basic terminal characteristic 

s 


P2 = 8 (default) 


24 23 16 15 


page 

width 

type 

class 

page 

length 

basic terminal characteristic 

s 

extended terminal characteristics 


ThePl argument points to a variable length block, as shown in Figure 8-7. 
With the exception of terminal characteristics, the contents of the block are 
the same for both the set mode and set characteristics functions. 

the buffer ' the device class is DC$_TERM, which is defined by the 
$DCDEF macro. The terminal type is defined by the $TTDEF macro, for 
^ m P' e ' TT$_LA36. The page width is a value in the range of 1 through 
511. The page length is a value in the range of 0 through 255. Table 8-5 
lists the values for terminal characteristics. Table 8-6 lists the extended 

characteristics. Characteristics values are defined by the $TTDEF and 
$TT2DEF macros. 

Note: Make sure that the selected device is a terminal before performing any set 
mode function, particularly when using SYS$INPUT or SYS$OUTPUT. 

The P3 argument defines the device speed, such as TT$C_BAUD_300 The 
low eight bits specify the transmit speed, and the high eight bits specify the 
receive speed. If no receive speed is specified, the indicated transmit speed 
is used for both transmitting and receiving. If neither the transmit nor the 
receive speed is specified (P3 = 0), the baud rate is not changed. The terminal 
driver ignores the receive speed bits for interfaces that do not support split- 
speed operation. While speeds up to 19.2K baud can be specified; not all 
controllers support all speed combinations. Refer to the associated hardware 
documentation to determine which speeds are supported by your controller. 

P4 contains fill counts for the carriage-return and line-feed characters Bits 0 
through 7 specify the number of fill characters used after a carriage return 
Bits 8 through 15 specify the number of fill characters used after a line feed. 

P4 is applicable only if TT$M_CRFILL or TT$M_LFFILL is specified as a 
terminal characteristic for the current QIO request; see Table 8-5. 
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Several parity flags can be specified in the P5 argument. 

• TT$M_ALTRPAR—Alter parity. If set, check the state of TT$M_PARITY 
and TT$M_ODD and, if indicated, change the parity. Otherwise, ignore 
these bits. TT$M_ALTRPAR is not supported for LAT devices. 

• TT$M_PARITY—Enable parity on terminal line if set, disable if clear. 

• TT$M_ODD—Parity is odd if set. 

• TT$M_ALTDISPAR—Alter dismiss parity errors. If set, check the state 
of TT$M_DISPARERR. 

• TT$M_DISPARERR—Dismiss parity errors. If this mode is set, input 
errors with a parity error flagged are discarded and no error is reported. 

Note* If parity is enabled, the DZ11 generates a parity check bit to detect 

parity mismatch. Unless TT$M_DISFARERR is enabled, parity errors 
that occur during an I/O read operation are fatal to the operation. 
Parity errors that occur on input characters (that is, keys pressed on 
the keyboard) when no I/O operation is in progress might result in a 

character loss. 

• TT$M_BREAK—Generate a break if set. The break 1 * me £?p t I “p t p 1 f 
this bit is turned off. TT$M—BREAK is supported by the LTDRIVER for 
terminal servers that support the break capability, such as the 
DECserver 200 and DECserver 500. However, in the case ot LAi 
terminals, the terminal server controls the duration of the break. 

• TT$M —ALTFRAME—If set, the four low-order bits of P5 become the 
frame size. Note that the frame size is for data bits only and is exclusive 
of parity. TT$M —ALTFRAME is not supported for LAT devices. 

To take the existing parity settings, modify them, and use them in the set 

mode or set characteristic function, move the byte starting at the second 

nibble of the buffer that is going to be used in the P5 argument. For example, 

thp following instructions change the parity from even to odd. 


insv iosb+6, #4, #8, flags 

bisl #tt$m_altrpar!tt$m_odd!tt$m_parity, flags 

The following instruction then resets the parity to its original state: 
bid #tt$m_odd!tt$m_parity, flags 

See Section 8.2.5 for information about the SET TERMINAL/FRAME 
command. 

Application programs that change terminal characteristics should perform the 
following steps: 

1 Use the IO$_SENSEMODE function to read the current charactenstics. 

2 Modify the characteristics. 

3 Use the set mode function to write back the results. 

4 If the characteristic is intended to be reset when the image exits, the 
application must perform this operation. 

Failure to follow this sequence will result in clearing any previously set 
characteristic. 
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Two stop bits are used only for data rates less than or equal to 150 baud; 
higher data rates default to one stop bit. M 

Jt 3nd characterist ics functions can take the enable 
CTRVC A ST enable CTRL/Y AST, enable out-of-band AST, hangup, set 
modem, broadcast, and loopback function modifiers that are described in the 
next several sections. 

Note: If an attempt is made to turn on TT2$V_FALLBACK for a disconnected 
virtual terminal (_VTAx:) or if the Terminal Fallback Facility has not 
been activated, the status code SS$_BADPARAM will be returned For 
° rmah0n ° n TFF ' re£er t0 thC VMS Terminal Fa "back Utility 


8.4.3.1 


8.4.3.2 


Hangup Function Modifier 

The hangup function disconnects a terminal that is on a dial-up line. (Dial-up 
ines are described in Section 8.2.3.) The following combinations of function 
code and modifier are provided: 

• IO$_SETMODE!IO$M_HANGUP 

• IO$_SET CH AR!IO$M _H ANGUP 

The hangup function modifier takes no arguments. SS$ NORMAL is 
returned in the I/O status block. 1S 


Enable CTRL/C AST and Enable CTRL/Y AST Function Modifiers 

rTPT S /vTci e r funCtl0nS Can take the enable CTR L/C AST and enable 
CTRL/Y AST function modifiers. These function modifiers request the 

CTRL/C trOTm /Y e Tt an f n ST ^ the r u ec I uestin g P rocess when you press 
CTRL/C or CTRL/Y The following combinations of function code and 
modifier are provided: 

• IO$_SETMODE!IO$M_CTRLCAST—Enable CTRL/C AST 

• IO$_SETMODE!IO$M_CTRLYAST—Enable CTRL/Y AST 

These function code modifier pairs take the following device- or function- 
dependent arguments: 6 

PI—Address of the AST service or 0 if the corresponding AST is disabled 

• P2—AST parameter 

P3—.Access mode to deliver AST (maximized with caller's access mode) 

If the respective enabling is in effect, pressing CTRL/C or CTRL/Y gains the 
attention of the enabling process (see Table 8-2). 7 8 * th<? 

Afte^theTqT C C J RL/Y j? ST one ‘ time enabling function modifiers. 
After the AST occurs, it must be explicitly reenabled by one of the two 

function code combinations before an AST can occur again This function 
code ts also used to disable the AST. The (unction is subject to As/q^otas. 

You can have more than one CTRL/C or CTRL/Y enabled; pressing CTRL/C 

InH hT P e T! SU u S in the deliver y of a11 CTRL/C ASTs. ASTs are queued ' 
and delivered to the user process on a first-in/first-out basis for each access 

AST or rTR?7v aqt * 3re pr ° C f Sed in the reverse order of the CTRL/C 

(on a Iast-in/te,-ow bSsP ' ^ iSS “ ed *° * he * ermlnal driver 
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If no enable CTRL/C AST is present, the holder of an enable CTRL/Y 
AST receives an AST when CTRL/C is pressed; camage-retum/line-feed 
combination, *Y, and RETURN are echoed. 

Figure 8-9 shows the relationship of CTRL/C and CTRL/Y with the out-of- 
band function. If CTRL/C or CTRL/Y is an enabled out-of-band character, 
any out-of-band ASTs specified for this character are dehvered^ If the 
IO$M_ INCLUDE function modifier is included in the ° u ,t • i 
request for this character, an enabled CTRL/C or CTRL/Y AST is also 

delivered. 

Enable CTRL/C AST requests are flushed by the Cancel I/O on Channel 
($CANCEL) system service. Enable CTRL/Y AST requests are flushed by the 
Deassign I/O Channel ($DASSGN) system service. 

CTRL/Y is normally used to gain the attention of the command mte^reter 

and to input special commands such as DEBUG, STOP, and CONTI . 
Programs that are run from a command interpreter should not enabl 
CTRL/Y Because ASTs are delivered on a first-in/first-out basis, the 
command interpreter's AST routine gets control first, and might not allow 
the program's AST to be delivered at all. Programs that require the use of 
CTRL/Y should use the LIB$DIS ABLE-CTRL RTL routine to disable DCL 
recognition of CTRL/Y. 

Section 8.2.1.2 describes other effects of CTRL/C and CTRL/Y. 


8 4 3 3 Set Modem Function Modifier 

The set modem function modifier is used in maintenance operations to allow 
a process to activate and deactivate modem control signals. Both set mode 
and set characteristics functions can take the set modem function modifier. 
The following combinations of function code and modifier are provided. 

• IO$_SETMODE!IO$M_SET_MODEM!IO$M_MAINT 

• IO$_SETCH AR!IO$M _SET—MODEM!IO$M —MAINT 

These function code modifier pairs take the following device- or function- 
dependent argument: 

• pi_The address of a quadword block that specifies which modem control 

signals to activate or deactivate 

Figure 8-8 shows the format of this block. 

Figure 8-8 Set Mode PI Block 
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The modem on and modem off fields, in combination 
specify one or more of the following values: 


or separately, can 


• TT$M_DS_RTS—Request to send (RTS) 

• TT$M_DS_DTR—data terminal ready (DTR) 

• TT$M_DS_SECTX—Transmitted backward channel data (Sec Txd) 


The $TTDEF macro defines the values for these values. These values can 
only be specified if the terminal characteristic TT$M_MODEM is not set 
Otherwise, an error (SS$_ABORT) will result. 

Note: Because the DMF32 does not provide the secondary transmitted data 

signal (Sec Txd), the driver sets the secondary request to send the signal. 
DMF32 h ° Uld C ° nneCt a )um P er cable between pins 14 and 19 on the 


8.4.3.4 Loopback Function Modifier 

The loopback function modifier is used in maintenance operations to place 
the terminal line in a hardware loopback mode. Data transmitted to a line 
m this mode is returned as receive data. If the controller does not support 
loopback mode or the terminal line has the TT$M_MODEM characteristic 
f e !' a ." er . ror status (SS$_ABORT) is returned. Both set mode functions can 
ake the loopback function modifier. The following combinations of function 
code and modifier are provided: 

• IO$_SETMODE!IO$M_LOOP!IO$M_MAINT 

• IO$_SETCHAR!IO$M_LOOP!IO$M_MAINT 


Data transmitted in the loopback mode should only be written in records 
less than or equal to the size of the type-ahead buffer (see Section 8 2 15) 
Programs that use the loopback function modifier should incorporate a one- 
second delay to allow the controller to enable the loopback mode after the 
request is posted. Write requests should also include the IO$M_NOFORMAT 
function modifier to prevent terminal driver from formatting input or output 

Note: The serial line interfaces for the VAX 8200 processor implement an 
internal loopback bus that is common to all four serial lines The 

YnluJ k ° W \ a !l SCrial U ? eS °P® ratin 8 in loopback mode to transmit 

In f ll i, the b n S <\u he Same t . ime * If more than one serial line writes data 
to the bus, all of the transmitted data is combined and made available 

h» e H « Vm8 » e r d ° f ?° Se SJne serial lines - Thus ' the received data 
may be different from the transmitted data if more than one serial line 

is operating m loopback mode at the same time. To prevent receiving 
loopba^k r mode data/ y ° U mU8t mU8t " 0t operate multi Pl e serial lines in 


The VMS operating system provides another function modifier to reset 
a terminal line previously placed in loopback mode. The following 
combinations of function code and modifier are provided: 

• IO$_SETMODE!IO$M_UNLOOP!IO$M_MAINT 

• IO$_SETCHAR!IO$M_UNLOOP!IO$M_MAINT 


8-46 










Terminal Driver 

8.4 Terminal Function Codes 


Programs that use the unloop function modifier should inonponte . one- 
second delay to allow the controller to reset the loopback mode after the 
request is posted. 

Note: IO$M_LOOP and IO$M_UNLOOP are not supported for LAT devices. 


0435 Enable Out-of-Band AST Function Modifier 

The enable out-of-band AST function modifier requests that the terminal 
driver queue an AST for the requesting process when you enter ® n y °ne of 32 
control characters. The following combinations of function code and modifier 
are provided: 

• iO$_SETMODE!IO$M_OUTBAND—Enable out-of-band AST 

• IO$_SETCHAR!IO$M_OUTBAND—Enable out-of-band AST 

These function code modifier pairs take the following device- or function- 
dependent arguments: 

. Pi-Address of the AST service or 0 if the AST entered on this channel 
is to be canceled. (The AST parameter will be the out-of-band character.) 

• p2—Address of a character mask with the same format as the short form 
terminator mask (see Section 8.4.1.2). 

• P3—Access mode to deliver AST (maximized with the caller's access 
mode). 

The IO$_SETMODE!IO$M _OUTBAND function can optionally take the 
following function modifiers: 

• IO$M_INCLUDE—Include the character typed in the data stream. 

• IO$M_TT_ABORT—Allow current read and write operations to be 
aborted. (The IOSB for aborted operations returns the status 
SS$_CONTROLC.) 

If an out-of-band AST is in effect, pressing any control character specified in 
the P2 mask gains the attention of the enabling process. Figure 8-9 shows the 
relationship of the out-of-band function with some of the control characters. 

You can have only one out-of-band AST enabled per channel. 

Out-of-band ASTs are repeating ASTs; they continue to ^delivered untU 
specifically disabled. Out-of-band AST enables are flushed by the Cancel I/O 
on Channel ($CANCEL) system service. 
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8.4.3.6 


Figure 8-9 Relationship of Out-of-Band Function with Control 
Characters 



ZK-1202-82 


Broadcast Function Modifier 

The broadcast function modifier allows you to turn on or turn off selected 

codP ^nH req H U 1? ter identi * ers < IDs )- T he following combination of function 
code and modifier is provided: 


• IO$_SETMODE!IO$M_BRDCST 
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This function code modifier pair takes the following device- or function- 
dependent arguments: 

. pi— A buffer that contains the bits that specify the requester IDs to be 

broadcast 

• P2—The length of the PI buffer (default is eight bytes) 


The first longword of PI is reserved for use by DIGITAL facilities, as shown in 
Table 8-12 The symbols are defined in the system macro library ($BRKDEr). 
The second longword is for customer use to specify selected bits. If any bit is 
set in the PI buffer, that particular requester ID is turned off for broadcast. 


Table 8-12 Broadcast Requester IDs 

Bit Meaning 


BRK$C_DCL 

BRK$C_GENERAL 

BRK$C_MAIL 

BRK$C_PHONE 

BRC$C_QUEUE 

BRK$C_SHUTDOWN 

BRK$C_URGENT 

BRK$C_USERn 


Disables broadcasts by CTRL/T 

Disables broadcasts by the DCL command REPLY and the 
SYS$BRDCST system service 
Disables broadcasts by the Mail Utility 
Disables broadcasts by the Phone Utility 
Disables broadcasts about batch and print queues 
Disables broadcasts about system shutdown 
Disables broadcasts labeled URGENT by the REPLY 
command 

Disables broadcasts by images associated with the 
specified value; n can be any decimal integer between 1 
and 16 


8.4.4 LAT Port Driver QIO Interface 


The LAT (Local Area Transport) port driver accomodates I/O requests from 
application programs for connections to remote devices on one or more 
terminal servers, and I/O requests that support other miscenaneous functions. 
A remote device, such as a printer, can be shared in a LAT coi^guration. 
Before an application program can access a remote device, the VMS system 
manager must create logical devices on the VMS operating system and 
map them to physical devices connected to terminal, servers, treating and 
mapping these logical devices can be done either with the LAT Control 
Program (LATCP) Utility or with a $QIO request from a program that has 
PHYS—IO privilege. Once mapped, application programs can establish and 
terminate connections to these remote devices. 

This section describes the QIO interface to the LAT port driver (LTDRIVER) 
and the functions and function modifiers you use to establish and terminate 

connections to remote devices. The QIO interface ^^fP^XTsKurS 5 
to access and modify information contained in the LTDRIVER data sutures 
and to initiate events and obtain status information. You must use these QIO 
functions to establish a connection to a remote device from an application 
program. DIGITAL does not support any other methods of connection. 

The LTDRIVER responds to TEST SERVICE commands issued at terminal 
servers that support the TEST SERVICE command, such as the DECserver 
200 and DECserver 500. 
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8.4.4.1 


LAT devices can use all read and write function modifiers listed for the 
terminal driver function codes except those modifiers that apply to modems 
(see Sections 8.4.1 and 8.4.2). 

The VMS operating system does not support the following set mode or set 
characteristics function code modifiers for LAT devices: 

• IO$M_LOOP 

• IO$M_UNLOOP 

• TT$M_ALTRPAR 

• TT$M —ALTFR AME 

• TT$M_MODEM 

• TT$M_READSYNC 

• TT2$M_SETSPEED 


With LAT devices, the terminal server, rather than the VMS host, handles 
flow control to the physical device. A separate flow control mechanism exists 
between the server and the host. 


LAT Port Driver Functions 

The VMS operating system provides the following combinations of function 
code and modifier: 

• IO$_TTY_PORT!IO$M_LT_CONNECT—Requests the LAT port driver 
make a connection to a remote device on a server. 

IO$__TTY__PORT!IO$M_LT_DISCON—Requests the LAT port driver 
terminate the LAT connection to the remote device. 

• IO$_TTY_PORT!IO$M_LT_MAP_PORT—Associates a specific port on a 
terminal server with a LAT (LTAxxx:) device. Equivalent to the LATCP 
command SET PORT LTAxxxx:/NODE=server-name/PORT=port-name. 

• IO$_TTY_PORT!IO$M_LT_RATING—Sets a static rating for a VMS 
service. This QIO is equivalent to the LATCP command 

SET SERVICE/STATIC_RATING=n. 

The LAT port driver can only connect to a remote device if it is currently not 
in use. Table 8-13 lists the conditions that can occur when an application 
program issues an IO$M_LT_CONNECT request for a connection to a 
remote device After a request for a connection is queued on the terminal 
server, the QIO request is not completed until the connection is established 
rejected, or timed out. 
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Table 8-13 IO$M LT COIMNECT Request Status 


Event 

IOSB Status 

Explanation 

Connection established 

SSS—NORMAL 

The connection is successful, 

and the device is ready to use. 

Connection timeout 

SS$_TIMEOUT 

The connection timed out. The 
server is not available, or an 



incorrect server name was 
specified. The timeout period is 

5 seconds. 

Connection rejected 

SS$_ ABORT. 

10SB+2 contains 

LAT rejection code. 

The connection cannot be made. 
See Table 8-14 for possible 
reasons. The LAT port driver 
updates the I/O status block. 

Connection request 
invalid 

No status. 
SS$_ILLIOFUNC 
returned in Register 
0 . 

The QIO request is not to an 
applications port. The LAT 
port driver rejects the request 
immediately. 

Connection already 
established on port 

No status. 

SS$_DEV ACTIVE 
returned in Register 
0 . 

The QIO request is for an 
applications port already in use. 
The LAT port driver rejects the 
request immediately. 


After you enter a disconnect request (IO$_TTY_PORT!IO$M_LT DISCON), 
the applications port's UCB goes off line momentarily. A connect request 
(IO$_TTY_PORT!IO$M_LT_CONNECT) may return a SS$_DEVACTIVE 
status if the connect request was immediately preceded by a disconnect 
request. In this case, reenter the connect request. 

The IO$M_LT_MAP—PORT modifier accepts two arguments: PI and P2. PI 
is the address of an item list, which must contain the node name, and either 
the port name or the service name of the remote terminal server port. ( ese 
names must be defined locally on the terminal server) The hem list can also 
contain the VMS link name and the terminal server Ethernet address The 
item list, which must be in type 3 format (see Figure 8-10), is terminated by a 
longword of 0. The item list contains the following parameters: 

• lO$V_LT_MAP_NODNAM— The node name. The node name is the 
name of the terminal server where the application device is located. 

• IO$V_LT_MAP_PORNAM—The port name. 

• IO$V_LT_MAP_SRVNAM—The service name. 

• IO$V_LT_MAP—LNKNAM—The Ethernet link name, which must be 
provided if the VMS service node has more than one Ethernet controller. 

• TOfcV LT_MAP_NETADR—The address of the quadword containing the 
Ethernet address of the terminal server. IO$V_LT_MAP_NETADR can be 
substituted for IO$V_LT_MAP_NODNAM. 


The P2 argument for IO$M_LT_MAP_PORT is a longword that passes 
queued status. Bit 0 cleared means nonqueued; bit 0 set means queued. 
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Figure 8-10 IO$M_LT_MAP_PORT Item List 




1 


| item 2...n 

I itemlist terminating 
/ longword 


ZK-6315-HC 


8.4.4.2 


The IO$M_LT_RATING modifier accepts two arguments: PI and P2 PI 
is the address of the string descriptor that contains the service name, which 
must already exist. P2 is the rating to assign the service. Ratings range from 
0 to 255 (decimal). 

Table 8-14 lists the possible status of the I/O Status Block after a 
IO$M_LT_MAP_PORT or IO$M_LT_RATING request. 


Table 8-14 IO$M_LT_MAP_PORT and IO$M_LT_RATING Request 
Status 


Event 

Contents of I/O Status Block and RO 

Operation successful 

SS$_NORMAL 

Illegal or incomplete parameter list; 
non-existent service 

SS$_BADPARAM 

Access violation in one of the 
arguments 

SS$_ACCVIO 

No privilege 

SS$NOPRIV 


Application Services Creation 

Rather than the normal timesharing service offered by the VMS operating 
system VMS application programs can make use of LAT application services 
that allow terminal server users to connect to a specialized application 
To do this, the system manager must create LAT ports that are dedicated 
to a particular application service. When a terminal server user uses the 
terminal server CONNECT command to connect to an application service, the 
connection is directly to the VMS application program that controls a LAT 
port (LTA device) associated with that service. In this case the VMS prompt 
Username: is not received. DIGITAL recommends that you create application 
services for VMS service nodes in the following order: 

1 Define the dedicated ports in LTLOAD.COM and execute the command 
procedure in SYSTARTUR_V50.COM. (Refer to the VMS LAT Control 
Program (LATCP) Manual and Guide to Setting Up a VMS System for 
additional information.) 
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2 Run the application program. Within the application P ro gram allocate 
dedicated ports with the same name as those defined in LTLOAD.COM. 
Use the Assign I/O Channel ($ASSIGN) system service to assign service 
channels to the ports. 

3 Post a read request to the dedicated ports. When the terminal user 
connects to the service and presses the RETURN key, the application 
program can perform I/O to the dedicated port. 

4 To break the connection, use the Deassign I/O Channel ($DASSGN) 
system service to deassign the channel and the Deallocate Device 
($DALLOC) system service to deallocate the device. The application 
program must reallocate the port and reassign the channel in preparation 
for the next connection. 

An example of the application service concept is a VMS program that provides 
the time of day. For this example, the system manager includes the following 
lines in LTLOAD.COM (or enters them manually in the LATCP program): 

CREATE SERVICE TIME/ID="At the tone, the time will be" 

CREATE PORT LTA99:/DEDICATED 

SET PORT LTA99:/DEDICATED/SERVICE=TIME 

An application program then assigns a channel to device LTA99. When 
a terminal server user types CONNECT TIME, the user is connected to 
this application program, and the program prints out the time of day. the 
program then deassigns the channel, which disconnects the server user. 

A system manager may associate more than one LAT port with the same 
service In that case, the application program that offers the service should 
assign channels to all of the LTA devices created for that service. 


8 4 4.3 Hangup Notification 

To allow notification by the terminal driver of abnormal termination dunng 
write operations, you should enable a CTRL/Y AST on the channel (see 
Section 8 4 3 2). This ensures that the terminal dnver notifies application 
programs, which are writing data, of an abnormal connection termination 
Note that the VMS operating system does not return an AST parameter to the 
CTRL/Y AST routine. 

When an application program with a pending read request has an abnormal 
LAT connection termination, the VMS terminal dnver returns a SS$_ 
HANGUP status in the first word of the IOSB. 


8.4.5 Sense Mode and Sense Characteristics 


The sense mode and sense characteristics functions sense the characteristics 
of the terminal and return them to the caller in the I/O status block. The 
following function codes are provided: 

• IO$_SENSEMODE 

• IO$_SENSECHAR 

IO$_SENSEMGDE returns the temporary characteristics of the terminal (the 
characteristics associated with the current process), and IO$^ENSECHAR 
returns the permanent characteristics of the terminal. IO$^ENSEMODE 
is a logical I/O function and requires no privilege. IO$_SENSELHAK is a 
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physical I/O function and requires the privilege necessary to perform physical 

These function codes take the following device- or function-dependent 
arguments: 

• PI—Address of a characteristics buffer 

• P2—Length of characteristics buffer (default length is 8 bytes) 

The PI argument points to a variable-length block, as shown in Figure 8—11. 

Figure 8-11 Sense Mode Characteristics Buffer 
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P2 = 12 


8.4.5.1 


In the buffer, the device class is DC$_TERM, which is defined by the 

J he terminal type is defi ned by the $TTDEF macro, such 
as i 13>_LA36. The maximum entry for buffer size (page width) is 255. 
Table 8-5 lists the values for terminal characteristics. Table 8-6 lists the 
^dfn ded terminal characteristics. Characteristics values are defined by the 
$TTDEF macro. 

The sense mode and sense characteristics functions can take the type-ahead 
count, read modem, and broadcast function modifiers described in the next 
few sections. 


Type-ahead Count Function Modifier 

The type-ahead count function modifier returns the count of characters 
presently in the type-ahead buffer and a copy of the first character in the 

utrvtw P1 ar 8 ument Points to a characteristics buffer returned 

by IO$M_TYPEAHDCNT. Figure 8-12 shows the format of this buffer. 
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Figure 8-12 Sense Mode Characteristics Buffer (type-ahead) 
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Figure 8-13 Sense Mode PI Block 
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8.4.5.2 Read Modem Function Modifier 

The read modem function modifier allows access to controller-dependent 
information. The following combinations of function code and modifier are 
provided: 

• IO$_SEN SEMODE!IO$M —RD—MODEM 

• IO$_SENSECHAR!IO$M_RD_MODEM 

These function code modifier pairs take the following device- or function- 
dependent argument: 

• pi—The address of a quadword block 
Figure 8-13 shows the format of this block. 

The receive modem field returns the value of the current input modem 
signals. Any or all of the following signals can be returned: 

• TT$M_DS_DSR—Data set ready (DSR) 

• TT$M_DS_RING—Calling indicator (RING) 

• TT$M_DS_CARRIER—Data channel received line signal detector 
(CARRIER) 

• TT$M_DS_CTS—Ready for sending (CTS) 

• TT$M_DS_SECREC—Received backward channel data (Sec RxD) 

The $TTDEF macro defines the symbols for the receive modem field. 
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The controller type field returns the type of terminal controller in use by the 
currently active terminal line. The $DCDEF macro defines the symbols for 
the following types of controllers: 

• DT$_DZ11—DZ11 and DZV11 

• DT$_DZ32—DZ32 

• DT$_DMF32—DMF32 

• DT$_DMB32—DMB32 

• DT$_DMZ32—DMZ32 

• DT$_DHV—DHV11 

• DT$_DHU—DHU11 

• DT$_LAT—LAT server 

The IO$M_RD_MODEM function modifier is not supported for LAT devices. 

8.4.5.3 Broadcast Function Modifier 

The broadcast function modifier returns those bits that have been set 
by the set mode function modifier IO$M_BRDCST (see Table 8-12 in 
Section 8.4.3.6). The following combination of function code and modifier is 
provided: 

• IO$_SENSEMODE!IO$M_BRDCST 

This function code modifier pair takes the following device- or function- 
dependent arguments: 

• PI—A buffer that contains the bits that specify the requester IDs to be 
broadcast. (If the bit is set in the first longword, that particular command 
is turned off for broadcast.) 

• P2—The length of the PI buffer. 


I/O Status Block 

The I/O status block (IOSB) formats for the read, write, set mode, set 
characteristics, sense mode, sense characteristics, and LAT port driver I/O 
functions are shown in Figures 8-14, 8-16, 8-17, and 8-18. Figure 8-15 
shows the IOSB format for the itemlist read function. Appendix A lists the 
status returns for these functions. (The VMS System Messages and Recovery 
Procedures Reference Volume provides explanations and suggested user actions 
for these returns.) 
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Figure 8-14 IOSB Contents—Read Function 
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Figure 8-15 IOSB Contents—Itemlist Read Function 
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Figure 8-16 IOSB Contents—Write Function 
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Figure 8 17 IOSB Contents—Set Mode, Set Characteristics, Sense 
Mode, and Sense Characteristics Functions 
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In Figure 8-14, the offset to terminator at IOSB+2 is the count of characters 
before the terminator character (see Section 8.4.1.2). The terminator character 
is in the buffer at the offset specified in IOSB+2. When the buffer is full, 
the offset at IOSB+2 is equal to the requested buffer size. At the same time, 
IOSB+4 is equal to 0. In the case of multiple character escape sequences that 
act as terminators, the terminator at IOSB+4 is the first character (ESC) of the 
escape sequence. IOSB+6 contains the size of the terminator string, usually 
1. However, in an escape sequence, IOSB+6 contains the size of the validated 
escape sequence (see Section 8.2.1.4). The sum of IOSB+2 and IOSB+6 is the 
number of characters in the buffer. 

In Figure 8—15 the terminator position word contains a number, the character 
of which is determined by the mode of operation. For itemlist read operations 
that do not specify TRM$K_EM_RDVERIFY, this word contains the number 
of characters from the end of the buffer to the cursor location at the time the 
terminator character was received. If TRM$K_EM_RDVERIFY is specified, 
the terminator position word contains the offset into the buffer from the 
nonverified character. 

For normal read operations, IOSB+5 and IOSB+7 are returned as zero For 
itemlist read operations, IOSB+5 is returned as -1, and IOSB+7 is the cursor 
offset from the end of line when the read operation terminates. 

In Figure 8-16, the remote terminal driver does not return the number of 
lines output or the cursor position. 

When an application program makes an I/O request for a connection to 
a remote device on a terminal server, the LAT port driver places status 
information about the request into the first word of the I/O status block as 
shown in Figure 8-18. Tables 8-13 and 8-14 list the possible status returns. 

If the server rejects the request, the LAT port driver returns a numeric LAT 
rejection code in the second word of the I/O status block. Table 8-15 lists 
the LAT rejection codes. 
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Figure 8-18 IOSB Contents—LAT Port Driver Function 
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Table 8-15 LAT Rejection Codes 


Value 

Reason 

0 

Unknown. 

2 

System shutdown in progress. 

5 

Insufficient resources at server. 

6 

Port or service in use. 

7 

No such service. 

8 

Service is disabled. 

9 

Service is not offered on the requested port. 

10 

Port name is unknown. 

13 

Immediate access rejected. 

14 

Access denied. 

15 

Corrupted request. 

16 

Requested function is not supported. 

17 

Session cannot be started. 

18 

Queue entry deleted by server. 

19 

Illegal request parameters. 


8.6 





• Example 8-1 shows several I/O operations using the full-duplex 
capabilities of the terminal. 

• Example 8-2 shows a typical read verify operation. 

• Example 8-3 shows how to connect to an applications (LT) device. 
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Example 8-1 illustrates some important concepts about terminal driver 
programming: assigning an I/O channel, performing full-duplex I/O 
operations, enabling CTRL/C AST requests, and itemlist read operations. 

The program is designed to run with a terminal set to full-duplex mode. The 
initialization code queues a read request to the terminal and enables CTRL/C 
AST requests. The main loop then prints out a random message every three 
seconds. When you enter a message on the terminal, the read AST routine 
prints an acknowledgment message and queues another read request. If you 
press CTRL/C, the associated AST routine cancels the I/O operation on the 
assigned channel and exits to the command interpreter. 

Examples 8-2 and 8-3 follow Example 8-1. 


Example 8—1 Terminal Program Example 


.TITLE FULL_DUPLEX TERMINAL PROGRAMMING EXAMPLE 
.IDENT /04/ 

************************** ********** t*************************,,.**,,^ 

TERMINAL PROGRAM 


♦t*********************************^,^.^^^^^^^^^^^^^^ 

.SBTTL DECLARATIONS 


Define symbols 


$ I0DEF ; Define I/O function codes 

$QI0DEF ; Define QIO definition codes 

$TRMDEF ; Define itemlist read codes 

Define macros 
.SHOW 

•MACRO ITEM LEN=0,CODE,VALUE 

.WORD LEN 

.WORD TRM$_'CODE' 

.LONG VALUE 
.LONG 0 
.ENDM ITEM 
.NOSHOW 


; Declare exit handler control block 
EXIT_HANDLER_BLOCK: 

; System uses this for pointer 
; Address of exit handler 
; Argument count for handler 
; Destination of status code 
; Status code from $EXIT 


.LONG 0 

.LONG EXIT.HANDLER 
.LONG 1 
.LONG STATUS 
STATUS: .BLKL 1 


Allocate terminal descriptor and channel number storage 


Example 8-1 Cont'd. on next page 
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Example 8-1 (Cont.) Terminal Program Example 


TT DESC' 

.ASCID /SYS$INPUT/ 

TT.CHAN: 

.BLKW 1 


; Logical name of terminal 
; TT channel number storage 


Define acknowledgment message. This is done right above input buffer 
so that we can concatenate the two together when the acknowledgment 
message is issued. 


ACK.MSG: 

.ASCII <CR><LF>/Following input acknowledged: / 
ACK_MSGLEN=.-ACK.MSG ; Calculate length of message 


; Allocate input buffer 

IN.BUFLEN = 20 
IN.BUF: 

.BLKB IN.BUFLEN 

IN.IOSB: 

.BLKQ 1 


Set length of buffer 
Allocate character buffer 
Input I/O status block 


Define out-of-band ast character mask 


CNTRLA.MASK: 

.LONG 0 

.LONG "B0010 : Control A mask 


; Define old terminal characteristics buffer 

OLDCHAR_BUF_LEN = 12 
OLDCHAR.BUF: 

.BLKB OLDCHAR_BUF_LEN 


; Define new terminal characteristics buffer 

NEWCHAR_BUF_LEN =12 
NEWCHAR.BUF: 

.BLKB NEWCHAR_BUF_LEN 


Define carriage control symbols 

CR=~X0D I Carriage return 

LF=*X0A ; Line feed 


Define output messages 

Output messages are accessed by indexing into a table of 
longwords with each message described by a message address and 
message length 


Example 8-1 Cont'd. on next page 
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Example 8-1 (Cont.) Terminal Program Example 


ARRAY: 


LONG 

10$ 

LONG 

15$ 

LONG 

20$ 

LONG 

25$ 

LONG 

30$ 

LONG 

35$ 

LONG 

40$ 

LONG 

45$ 


Table of message addresses and 
lengths 

First message address 
First message length 


Define messages 


10$: .ASCII <CR><LF>/RED ALERT!!! 

15$=.-10$ 


RED ALERT!!!/ 


20$: .ASCII <CR><LF>/ALL SYSTEMS GO/ 

25$=.-20$ 


30$: .ASCII <CR><LF>/WARNING.INTRUDER ALARM/ 

35$=.-30$ 


40$: .ASCII <CRXLF>/***** SYSTEM OVERLOAD *****/ 

45$=.-40$ 


Static QIO packet for message output using QI0$_G form 
WRITE.QIO: 

$QI0 FUNC=I0$ Jl/RITEVBLK! 10$M_BREAKTHRU! IO$M_REFRESH, - 

EFN=1 ; QIO packet 

Timer storage 
WAITIME: 


TIME: 


.LONG "10*1000*1000*3,-1 ; 3 second delta time 


.BLKQ 1 
•SBTTL START - MAIN ROUTINE 


; Current storage time used for 
; random number 


Example 8—1 Cont'd. on next page 
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+ + 

Functional description: 

******************************************************************** 
Start program 

******************************************************************** 


The following code performs initialization functions. 

It is assumed that the terminal is already in 
FULL-DUPLEX mode. 

NOTE: When doing QI0_S calls, parameters PI and P3-P6 should be 
passed by value, while P2 should be passed by reference. 


Input parameters: 
None 


Output parameters: 



None 


START: 

.WORD 



$ASSIGN_S DEVNAM=TT_DESC,- 



CHAN=TT_CHAN 


BLBS 

RO,10$ 


BRW 

ERROR 

10$: 

BSBW 

CHANGE_CHARACTERISTICS 


BSBW 

ENABLE.CTRLCAST 


BSBW 

ENABLE.OUTBANDAST 


BSBW 

ENABLE.READ 


MOVZWL 

TT_CHAN,WRITE_QI0+8 

; This loop outputs a message based on 

; delays for 3 

seconds 

LOOP: 




$GETTIM_S TIMADR=TIME 


BLBS 

RO,10$ 


BRW 

ERROR 

10$: 

EXTZV 

#6,#2,TIME,RO 


Entry mask 

Assign terminal channel using 
logical name and channel number 
No error if set 
Error 

Change the characteristics of 
terminal 

Allow CTRL/C traps 

Enable CTRL/A out-of-band AST 

Queue read 

Insert channel into 

static QIO packet 


random number and then 


; Get random time 
; No error if set 

; Load random bits into 
; switch 


MOVQ ARRAY[RO],- 

WRITE_QI0+QI0$_P1 


Load message address 
and size into QIO 
packet 


Example 8-1 Cont'd. on next page 
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; Issue QIO write using packet defined in data area 
$QI0W_G WRITE.QIO 

BLBS R0,5$ ; No error if set 

BRW ERROR 

; Delay for 3 seconds before issuing next message 
5$: 

$SETIMR_S EFN=#2.DAYTIM=WAITIME 


BLBS RO,20$ 

BRW ERROR 

20$: $WAITFR_S EFN=#2 

BLBS RO,LOOP 

BRW ERROR 

.SBTTL CHANGE.CHARACTER1STICS - CHANGE CHARACTERISTICS OF 

TERMINAL 

* + + 


; Timer service 
will set event flag 
in 3 seconds 
No error if set 

Wait for event flag 
No error if set 


Functional description: 

Routine to change the characteristics of the terminal. 

Input parameters: 

None 

Output parameters: 

RO - status from $QI0 call. 

R1 - R5 destroyed 


CHANGE.CHARACTERISTICS: 

$QI0_S CHAN=TT_CHAN,- 

FUNC=#IO$_SENSEMODE,- 
P1=0LDCHAR_BUF,- 
P2=#0LDCHAR_BUF_LEN 
BLBC RO,10$ 

$DCLEXH_S EXIT_HANDLER_BLOCK 

BLBS R0,5$ 

BRW ERROR 


Get current terminal 
characteristics 


Error if clear 

Declare exit handler to reset 
characteristics 


Example 8-1 Cont'd. on next page 
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5$: 

M0VC3 

#OLDCHAR_BUF_LEN.- ; 
OLDCHAR.BUF.- ; 
NEWCHAR.BUF 

Move old characteristics into 
new characteristics buffer 


BISL2 

#TT$M_NOBRDCST,- ; 

NEWCHAR.BUF+4 ; 

Set nobroadcast bit 


$QI0_S 

CHAN=TT_CHAN,- ; 

FUNC=#I0$_SETM0DE,- ; 

P1=NEWCHAR_BUF.- 
P2=#NEWCHAR_BUF_LEN 

Set current terminal 
characteristics 


BLBS 

RO.20$ ; 

No error if set 

10$: 

20$: 

BRW 

RSB 

ERROR 


•++ 

.SBTTL 

ENABLE.CTRLCAST - ENABLE 

CTRL/C AST 


Functional description: 

Routine to allow CTRL/C recognition. 

Input parameters: 

None 

Output parameters: 

None 


ENABLE.CTRLCAST: 

$QI0W_S CHAN=TT_CHAN,- 

FUNC=#I0$_SETM0DE!IO$M_CTRLCAST.- 
P1=CTRLCAST,- ; AST routine address 

P3=#3 ; User mode 

BLBS RO,10$ ; No error if set 

BRW ERROR 

10$: RSB 


.SBTTL ENABLE.OUTBANDAST - ENABLE CTRL/A AST 


+ + 


Functional description: 

Routine to allow CNTRL/A recognition. 

Input parameters: 

None 

Output parameters: 

None 


Example 8-1 Cont'd. on next page 
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ENABLE.OUTBANDAST: 

$QI0W_S CHAN=TT_CHAN,- 

FUNC=#I0$_SETM0DE!I0$M_0UTBAND,- 
P1=CTRLAAST,- ; AST routine address 

P2=#CNTRLA_MASK,- ; Character mask 

P3=#3 ; User mode 



BLBS 

RO,10$ 

; No error if set 


BRW 

ERROR 


10$: 

RSB 




.SBTTL 

ENABLE.READ - 

QUEUE A READ TO THE TERMINAL 

; + + 





Functional description: 


; Routine to queue a read operation to the terminal. 

; Input parameters: 

; None 

; Output parameters: 

; None 

; Define item list for itemlist read 
ITEM.LST: 

ITEM 0,MODIFIERS,- 

TRM$M_TM_CVTL0W!TRM$M 
ITEM 6,TERM,MASK.ADDR 


ITEM_LEN=.-ITEM.LST 
MASK.ADDR: 

.LONG 1@~XD 
.WORD 104 

ENABLE.READ: 

$QI0_S CHAN=TT_CHAN,- 


FUNC=#IO$_READVBLK!I0$M 
I0SB=IN_I0SB,- 
ASTADR=READAST,- 
P1=IN_BUF,- 
P2=#IN_BUFLEN,- 
P5=#ITEM_LST,- 
P6=#ITEM_LEN 
BLBS RO,10$ 

BRW ERROR 

; The queued read operation will not affect write operations due 
; to the fact that breakthru has been set for the write operations. 

10$: RSB 


Example 8-1 Cont'd. on next page 


; Must not be QIOW form 
; or read will block 
; process 
.EXTEND,- 

; AST routine to execute 
; on 

; Itemlist read address 
; Itemlist read size 
; No error if set 


; Convert lowercase to 
_TM_N0EDIT ; upper and inhibit line 
; editing 

; Set up terminator mask 


; Terminator mask is <CR> 
; and "$" 
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.SBTTL READAST - AST ROUTINE FOR READ COMPLETION 


Functional description: 

AST routine to execute on read completion. 

Input parameters: 

None 

Output parameters: 

None 



READAST: 

.WORD 

BLBS 

MOVZWL 

BRW 

10$: MOVZWL 

ADDL2 
$QI0_S 


~M<R2,R3,R4,R5> 
IN_I0SB,10$ 

in_iosb.ro 

ERROR 

IN_I0SB+2,R0 
#ACK_MSGLEN,RO 


CHAN=TT_CHAN,- 
FUNC=#IO$_WRITEVBLK,- 
P1=ACK_MSG,- 
P2=R0 


Procedure entry mask 
Check IOSB for success 
Put error status in RO 
Exit with error 
Get number of characters 
read into RO 

Add size of fixed acknowledge 
message 

Issue acknowledge 
message 


Process read message 


(user-provided code to decode command inserted here) 



BSBW ENABLE.READ ; Queue next read 

RET ; Return to mainline loop 

.SBTTL CTRLAAST - AST ROUTINE FOR CTRL/A 
.SBTTL CTRLCAST - AST ROUTINE FOR CTRL/C 
.SBTTL ERROR - EXIT ROUTINE 


Example 8-1 Cont'd. on next page 
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; + + 

; Functional description: 

; AST routine to execute when CTRL/C or CTRL/A is entered. 

; Input parameters: 

; None 

; Output parameters: 

; None 

CTRLCAST: 

CTRLAAST: 


.WORD 

~M<> 

; Procedure entry mask 

MOVL 

#1 ,R0 

; Put success in RO 

ERROR: $EXIT_S 

RO 

; Exit 

RSB 



.SBTTL 

EXIT_HANDLER 

- EXIT HANDLER ROUTINE 


++ 


Functional description: 

Exit handler routine to execute when image exits. It cancels 
any outstanding I/O on this channel and resets the terminal 
characteristics to their original state. 

Input parameters: 

None 

Output parameters: 

None 


EXIT.HANDLER: 

.WORD 

$CANCEL_S CHAN=TT_CHAN 

$QI0_S CHAN=TT_CHAN,- 

FUNC=#I0$_SETM0DE,- 
P1=0LDCHAR_BUF,- 
P2=#0LDCHAR_BUF_LEN 

RET 

.END START 


Procedure entry mask 

Flush any I/O on queue 

Reset terminal characteristics 
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Example 8-2 is an example of the read verify function. The program shows a 
typical build of itemlists (both the right and left fields), channel assignment, 
a right- and left-justified read verify operation, and then the read QIO 
operation. 

Example 8-2 Read Verify Program Example 


.TITLE READ.VERIFY - Read Verify Coding Example 
.IDENT 'V04-000' 

.SBTTL DECLARATIONS 
; Include files: 

$TRMDEF 
; Macros: 

.MACRO ITEM LEN=0,CODE.VALUE 
.WORD LEN 
.WORD TRM$_'C0DE' 

.LONG VALUE 
.LONG 0 
.ENDM ITEM 


; Equated symbols: 

INBUF.LEN = 20 
ESC = *X1B 


Own storage: 

Build item lists for the read verify QIO 


Right-justified field 


R_ITEM_LIST: 

ITEM 

CODE 

VALUE 

= MODIFIERS, - 
= TRM$M_TM_R_ JUST 

; Right justify 

ITEM 

CODE 

VALUE 

= EDITMODE, - 
= TRM$K_EM_RDVERIFY 

; Enable read verify 

ITEM 

CODE 

VALUE 

LEN 

= PROMPT, - 
= R_PROMPT_ADDR, - 
= R_PROMPT_LEN 

; Set up prompt 

ITEM 

CODE 

VALUE 

LEN 

= INISTRNG, - 
= R_INISTR_ADDR, - 
= R.INISTR.LEN 

; Set up initial string 

ITEM 

CODE 

VALUE 

= INIOFFSET, - 
= R_INISTR_LEN 


ITEM 

CODE 

VALUE 

LEN 

= PICSTRNG, - 
= R_PICSTR_ADDR, - 
= R_PICSTR_LEN 

; Set up picture string 

Example 8- 

2 Cont d. 

on next page 
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ITEM CODE = FILLCHR, - 

VALUE = <~k/* /> ; clear = *, fill = space 

R_ITEM_LIST_LEN = .-R_ITEM_LIST 

R_PROMPT_ADDR: 

•ASCII <ESC>/[12;12H$/ 

R_PROMPT_LEN = .-R_PROMPT_ADDR 

R_INISTR_ADDR: 

•ASCII / . / 

R_INISTR_LEN = .-R_INISTR_ADDR 

MASK = TRM$M_CV_NUMERIC!TRM$M_CV_NUMPUNC 

R_PICSTR_ADDR: 

.BYTE MASK 
•BYTE MASK 
•BYTE MASK 

•BYTE 0 ; Marker character 

•BYTE MASK 
.BYTE MASK 
.BYTE MASK 

R_PICSTR_LEN = .-R_PICSTR_ADDR 


; Left-justified field 
L_ITEM_LIST: 


ITEM 

CODE 

= MODIFIERS, - 



VALUE 

= TRM$M_TM_CVTLOW!TRM$M_TM_AUTO_TAB 

; Upcase input and 
; complete on field full 

ITEM 

CODE 

= EDITMODE, - 



VALUE 

= TRM$K_EM_RDVERIFY 

; Enable read verify 

ITEM 

CODE 

VALUE 

= PROMPT, - 
= L.PROMPT.ADDR, - 



LEN 

= L_PROMPT_LEN 

; Set up prompt 

ITEM 

CODE 

VALUE 

= INISTRNG, - 
= L_INISTR_ADDR, - 



LEN 

= L_INISTR_LEN 

; Set up initial string 

ITEM 

CODE 

VALUE 

= INIOFFSET, - 
= 0 


ITEM 

CODE 

VALUE 

= PICSTRNG, - 
= L_PICSTR_ADDR, - 



LEN 

= L_PICSTR_LEN 

; Set up picture string 

ITEM 

CODE 

= FILLCHR, - 



VALUE 

= <~A/* /> 

; clear = *, fill = space 

.LIST_LEN 

= . ~L_ 

ITEM_LIST 



L_PROMPT_ADDR: 

•ASCII <ESC>/[13;12H Enter Date: / 
L_PROMPT_LEN = .-L_PROMPT_ADDR 

L_INISTR_ADDR: 

•ASCII / - - / 

L_INISTR_LEN = .-L_INISTR_ADDR 
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MASKl = TRM$M_CV_NUMERIC 

MASK2 = TRM$M_CV_UPPER!TRM$M_CV_LOWER 


€ 


L_PICSTR_ADDR: 


.BYTE 

MASKl 

.BYTE 

MASKl 

.BYTE 

o ; 

.BYTE 

MASK2 

.BYTE 

MASK2 

.BYTE 

MASK2 

.BYTE 

o ; 

.BYTE 

MASKl 

.BYTE 

MASKl 

L.PICSTR.LEN = 

.-L_PICSTR_ADDR 

IN.IOSB: 

.BLKL 2 

TT.CHAN: 

.BLKW 1 

INBUF: 

.BLKB INBUF.LEN 

SYSINPUT: 

.ASCID /SYS$INPU‘ 

.ENTRY 

READ_VERIFY,~M<> 


Marker character 


marker character 


; Assign the channel to SYS$INPUT 

$ASSIGN_S - 

CHAN = TT.CHAN - 
DEVNAM = SYSINPUT 
BLBC RO,ERROR 


SYS$INPUT 
Branch on error 


; Clear the screen 
CLRQ -(SP) 

CALLS #2.G‘SCR$ERASE_PAGE 
BLBC RO,ERROR 


Do the right-justified read operation 


PUSHL #R_ITEM_LIST_LEN 
PUSHAB R_ITEM_LIST 
CALLS #2,D0_READ 
BLBC RO,ERROR 


Do the left-justified read operation 


PUSHL #L_ITEM_LIST_LEN 
PUSHAB L_ITEM_LIST 
CALLS #2,D0_READ 
BLBC RO.ERROR 


ERROR: 


Example 8-2 Cont'd. on next page 
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+ + 

DCLREAD - do the actual QIO 
Inputs: 

4(AP) the address of the itemlist 
8(AP) the length of the itemlist 


.ENTRY DCLREAD, ~M<> 

$QI0W_S CHAN = TT_CHAN - 

FUNC = #<IO$_READVBLK!IO$M_EXTEND>,- 

IOSB = IN_I0SB,- 

pi = inbuf,- 

p2 = #inbuf_len,- 

p5 = 4(AP),- 

P6 = 8(AP) 

BLBC R0,10$ ; Branch on error 

; Handle the input... 

10$: RET 

.END READ.VERIFY 


Example 8-3 requests a connection to an applications (LT) device. The 
program uses the terminal port function code (IO$_TTY_PORT) and the 
function code modifiers for the LAT port driver to solicit the connection to the 
applications device. (Note that the IO$_TTY_PORT function is not specific to 
LAT operations.) 

Example 8-3 also illustrates the use of the set rating (IO$M_LT_RATING) 
and map port (IO$M_LT_MAP_PORT) functions (see Section 8.4.4.1). 

See Section 8.4.4.2 for additional information on LAT application 
programming. 
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Example 8-3 LAT Application Device Program 


.TITLE LAT APPLICATION DEVICE PROGRAMMING EXAMPLE 

.IDENT l\.\l 

*************************************************************** 
LAT Application Device Program 

*************************************************************** 
.SBTTL DECLARATIONS 

Define symbols 


$I0DEF 

SQIODEF 

Declare exit handler control block 


; I/O function codes 
; QIO definition codes 


.LONG 

0 

; System uses this for pointer 

.LONG 

EXIT.HANDLER 

; Address of exit handler 

.LONG 

1 

; Argument count for handler 

.LONG 

STATUS 

; Destination of status code 


.BLKL 1 

; Status code from $EXIT 


STATUS: 

Allocate terminal descriptor and channel number storage 


TT_DESC: 

.ASCID 

/SYS$INPUT/ 

; Name of terminal 

TT_CHAN: 

.BLKW 

1 

; TT channel number storage 

LT.DESC: 

.ASCID 

/LATSPORT/ 

; Logical name of LT device, 

LT.CHAN: 

.BLKW 

1 

; define this to be the application 
; port created in LATCP 

; LT channel number storage 

; Append <CR><LF> to message 


; Allocate input 

buffer 


IN.BUFLEN = 80 
IN.BUF: 

.BLKB 

IN.BUFLEN 

; Allocate character buffer 

IN.IOSB: 

.BLKQ 

1 

; Input I/O status block (IOSB) 

SOL.IOSB: 

.BLKQ 

1 

; Solicitation connect IOSB 

MAP.IOSB: 

.BLKQ 

1 

; Map IOSB 

RATING_IOSB: 

.BLKQ 

1 

; Rating IOSB 

Example 8-3 Cont'd. on next page 
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SERVICE.DESC: 

.LONG SERVICE_NAME_LENGTH 

.ADDRESS SERVICE.NAME 

SERVICE.NAME: ; Service that was created by LATCP 

.ASCII /TIMESHARING/ 

SERVICE.NAME.LENGTH = . - SERVICE.NAME 

NEW.RATING: ; The new static rating value for it 

.LONG 100 

LATNOD: .ASCII /PLUTO/ 


NODLEN: .-LATNOD 

LATPORT: .ASCII /APPLIC.DEVICE/ 

P0RTLEN= .-LATPORT 

MAP.ITEMLIST: 

.WORD NODLEN 

.WORD IO$V_LT_MAP_NODNAM 

.ADDRESS LATNOD 

.LONG 0 

.WORD PORTLEN 

.WORD IO$V_LT_MAP_PORNAM 

.ADDRESS LATPORT 

.LONG 0 

.LONG 0 


; Define carriage control symbols 

CR=~XOD 

LF=~XOA 

OUT.MSGLEN = 2 
OUT.MSG: 

.ASCII <CR><LF> 



; Carriage return 
; Line feed 


Define output messages 

Messages are accessed by indexing into a table of longwords 
with each message described by a message address and length 


MSG.TABLE: 

.LONG 01$ 
.LONG 05$ 
.LONG 10$ 
.LONG 15$ 


.LONG 190$ 

.LONG 195$ 


; Table of message address 
; and length 
; First message address 
; First message length 
; Message address 
; Message length 


; Message address 
; Message length 


Example 8—3 Cont'd. on next page 
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Messages (Refer to the list of LAT rejection codes in Table 8-15.) 


01$: .ASCII 

05$=.-01$ 

/REASON UNKNOWN/ 

io$: .ASCII 

15$=.-10$ 

<CR><LF>/CONNECTION ESTABLISHED/ 

20$: .ASCII 

25$=.-20$ 

/SYSTEM SHUTDOWN IN PROGRESS/ 

50$: .ASCII 

55$=.-50$ 

/INSUFFICIENT RESOURCES/ 

60$: .ASCII 

65$=.-60$ 

/PORT OR SERVICE IN USE/ 

190$: .ASCII 

195$=.-190$ 

/ILLEGAL REQUEST PARAMETERS/ 


NOTCON: .ASCII <CR><LF>/CONNECTION REJECTED - / 

N0TC0NL=.-NOTCON 

Static QIO packets for message output using QI0$_G form 


WRITE_QI0: 

$QI0 

FUNC=IO$_WRITEVBLK!IO$M_BREAKTHRU!IO$M_REFRESH,- 
EFN=1 

ERROR.QIO: 

$QI0 

FUNC=IO$_WRITEVBLK!IO$M_BREAKTHRU!IO$M_REFRESH,- 
EFN=1 


Example 8-3 Cont'd. on next page 
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.SBTTL MAIN ROUTINE 

+ + 

Functional description: 


*********************************** ** ** * ******************* 


Main Program Routine 

********************** * *** *** ******** ****************** * *** 


The following code assigns a channel to the LTAxxx: 
application device and attempts to create a connection to 
that device. The connection status is displayed on 
the user's terminal. Input from the user's terminal 
is output on the LTAxxx device: CTRL/C entered by the 
user terminates the program. 

Input parameters: 

None 

output parameters: 

None 


START: 


.WORD 


; Assign channels 

$ASSIGN_S 

BLBS 

BRW 

10$: $ASSIGN_S 

BLBS 

BRW 


DEVNAM=TT_DESC, 
CHAN=TT_CHAN 
RO, 10$ 

ERROR 

DEVNAM=LT_DESC, 
CHAN=LT_CHAN 
RO, 20$ 

ERROR 


Entry mask 


Assign channel to user's 
terminal 
No error if set 
Else, error 

Assign channel to LT device 

No error if set 
Else, error 


Perform the privileged operations of changing a static service 
rating (an operation unrelated to the use of application devices but 
included here strictly as an example) and remapping the applications 
port. 


20$: BSBW LAT_SET_RATING 

BSBW LAT_MAP_PORT 


Change a static service rating 
Change the application port mapping 


Example 8—3 Cont'd. on next page 
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Enable CTRL/C on user terminal and CTRL/Y on LTA device. Post 
read to user terminal and solicit connection to application device. 
The CTRL/Y AST enable is done in the solicit connection AST so 
that a CTRL/Y is not returned before the solicit AST. This 
prevents the rejection errors from being displayed. 


30$: 


BSBW 

ENABLE.CTRLCAST 

BSBW 

SOL.CONNECT 

BSBW 

ENABLE.READ 

NOP 


BRB 

30$ 

RET 


.SBTTL 

ENABLE.CTRLYAST - 


; Enable CTRL/C ASTs 
; Try to connect to LT device 
; Queue read 

; Keep looping until CTRL/C 
Enable CTRLYAST on LTAxxx device 


++ 

Functional description: 


Routine to allow hangup notification. This routine enables 
CTRL/Y AST delivery for the LTAxxx: device. This routine 
is called if an abnormal termination occurs to the remote 
application device. 


Input parameters: 
None 

Output parameters: 
None 


ENABLE.CTRLYAST: 

$QI0W_S CHAN=LT_CHAN,- 

FUNC=#I0$_SETM0DE!IO$M_CTRLYAST,- 
P1=HANGUP,- ; AST routine address 

P3=#3 ; User mode 

BLBS RO, 10$ ; No error if set 

BRW ERROR 

10$: RSB 


Example 8-3 Cont'd. on next page 
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.SBTTL HANGUP - AST Routine for CTRL/Y 


Functional description: 

AST routine to execute when CTRL/Y status is returned for the 
application device. This status is returned when the 
connection to the remote device is abnormally terminated. 

Input parameters: 

None 

Output parameters: 

None 


HANGUP: 

.WORD 

MOVZWL 

BRW 

.SBTTL 


Functional description: 

Routine to queue a read to the terminal. The queued 
read will not affect writes due to the fact that 
breakthru has been set for writes. 


~M<> 

#SS$_HANGUP,RO ; Indicate hangup 

ERROR ; and exit 

ENABLE_READ - QUEUE A READ TO THE TERMINAL 


Input parameters: 
None 

Output parameters: 
None 


ENABLE.READ: 

$QI0_S CHAN=TT_CHAN, - ; Must not be QIOW form 

FUNC=#IO$_READVBLK,- 
I0SB=IN_I0SB,- 
ASTADR=READAST,- 
P1=IN_BUF,- 
P2=#IN_BUFLEN 

BLBS R0,10$ ; No error if set 

BRW ERROR 

10$: RSB 


Example 8-3 Cont'd. on next page 
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Example 8-3 (Cont.) LAT Application Device Program 

.SBTTL READAST - AST Routine for Read Completion 


Functional description: 

AST routine to execute on read completion. The data that 
was input from the users terminal is output on the 
application device. Another read request is then posted. 

Input parameters: 

None 

Output parameters: 

None 


READAST: 


.WORD 

*M<R2,R3,R4.R5> 

Procedure entry mask 

BLBS 

IN_I0SB,10$ 

Check IOSB for success 

MOVZWL 

IN_I0SB. RO 

Put error status in RO 

BRW 

ERROR 

Exit with error 

MOVZWL 

IN_I0SB+2,RO 

Get number of characters read 

ADDL2 

#OUT_MSGLEN,RO 

Add size of fixed ack 

$QI0_S 

CHAN=LT_CHAN.- 
FUNC=#IO$_WRITEVBLK,- 
P1=0UT_MSG,- 
P2=R0 

Output message to LT device 

BSBW 

RET 

NABLE.READ 

; Queue next read 

.SBTTL 

ENABLE.CTRLCAST - ENABLE CTRL/C AST 


++ 

Functional description: 

Routine to allow CTRL/C recognition on user's terminal 
Input parameters: 

None 

Output parameters: 


None 


ENABLE_CTRLCAST: 

$QI0W_S CHAN=TT_CHAN,- 

FUNC=#I0$_SETM0DE!IO$M_CTRLCAST,- 
P1=CTRLCAST,- ; AST routine 

P3=#3 ; User mode 

BLBS RO, 10$ ; No error if 

BRW ERROR 

10$: RSB 


address 

set 


Example 8-3 Cont'd. on next page 
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Example 8—3 (Cont.) LAT Application Device Program 


.SBTTL CTRLCAST - AST Routine for CTRL/C 

+ + 


Functional description: 

AST routine to execute when CTRL/C is received. The connection 
to the application device is stopped and the program is terminated 
with normal completion status. 

Input parameters: 

None 

Output parameters: 

None 


CTRLCAST: 



.WORD 

~M<> 


$QI0_S 

CHAN=LT_CHAN,- ; Disconnect session to LT device 

FUNC=#I0$_TTY_P0RT!I0$M_LT_DISC0N 

ERROR: 

$EXIT_ 

RSB 

RO ; Exit 


.SBTTL 

S0L_C0NNECT - Solicit Connection to LT Device 

; ++ 




Functional description: 

This routine issues the QIO to the LT driver to solicit 
the connection to the LT device. 

Input parameters: 

None 

Output parameters: 

None 


SOL.CONNECT: 

$QI0W_S CHAN=LT_CHAN,- 

FUNC=#I0$_TTY_P0RT!I0$M_LT_C0NNECT,- 
I0SB=S0L_I0SB 

BLBS RO,10$ 

BRW ERROR 

10 $: 

MOVL SOL.IOSB.RO 

BLBC RO.ERROR 

RSB 


Example 8-3 Cont'd. on next page 
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Example 8-3 (Cont.) LAT Application Device Program 

.SBTTL SOLAST - AST Routine for connection solicitation status 

; ++ 

; Functional description: 


AST routine to execute when connection solicitation is 
complete. If status is success, print success message and 
return. If status is rejection, print reject message, 
reject reason, and exit. If status is otherwise, exit. 

Input parameters: 

None 

Output parameters: 

None 


SOLAST: 


10 $: 


.WORD 

*M<> 

MOVZWL 

S0L_I0SB.R0 

BLBC 

RO.10$ 

MOVL 

R0.R1 

JSB 

WRITE.STATUS 

BSBW 

RET 

ENABLE.CTRLYAST 

CMPW 

RO.#SS$_AB0RT 

BNEQ 

ERROR 

$QI0W_G 

ERROR.QIO 

MOVZWL 

S0L_I0SB+2,R1 

MOVZWL 

TT_CHAN,ERR0R_QI0+8 

JSB 

WRITE.STATUS 

BRW 

ERROR 

STATUS: 

MOVQ 

MSG_TABLE[R1] 

WRITE_QI0+QI0$_P1 

MOVZWL 

TT.CHAN.WRITE.QIO+8 

$QI0W_G 

RSB 

WRITE.QIO 


Example 8-3 Cont'd. on next page 


Get return status 
If clear, error 
Copy success code for index 
Output success message 
Enable CTRL/Y ASTs 


Is this a rejected connection? 
If eq, output error message 
Output error message first 
Set R1 for offset into table 
Insert channel into QIO packet 
Output error reason 
Exit 


; Put message into QIO 
; Insert channel into QIO packet 
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Example 8-3 (Cont.) LAT Application Device Program 

.SBTTL EXIT.HANDLER: 

+ + 


Functional description: 

Exit handler routine to execute when image exits. It will 
cancel any outstanding I/O on these channels. 

Input parameters: 

None 

Output parameters: 

None 


EXIT_HANDLER: 

.WORD 

$CANCEL_S CHAN=TT_CHAN ; Flush any output 

$CANCEL_S CHAN=LT_CHAN 

RET 

.SBTTL LAT_MAP_PORT Map Port QIO 


Functional description: 

The following code performs a map port QIO. It uses an item 
list that specifies the names for the target server and port 
that is associated with the application port. 

Input parameters: 

None 

Output parameters: 

None 


LAT_MAP_PORT: 

$QI0W_S CHAN = LT.CHAN, - 

FUNC = #<I0$_TTY_P0RT!I0$M_LT_MAP_P0RT>, - 
IOSB = MAP.IOSB- 
P1 = MAP_ITEMLIST 

RSB 


Example 8-3 Cont'd. on next page 
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Example 8-3 (Cont.) LAT Application Device Program 


.SBTTL LAT_SET_RATING 


Functional description: 

The following code performs the set rating QIO. 

In this example, the rating for the service "TIMESHARING" 
is set to a static rating of 100. 

Input parameters: 

None 

Output parameters: 

None 


LAT_SET_RATING: 


$QI0W_S CHAN 
FUNC 
IOSB 
PI = 
P2 = 

RSB 


LT_CHAN, - 

#<I0$_TTY.PORT!IO$M_LT_RATING>, - 

RATING_IOSB,- 

SERVICE.DESC,- 

NEW_RATING 


.END START 


O 
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A I/O Function Codes 


This appendix lists the function codes and function modifiers defined in the 
$IODEF macro. The arguments for these functions are also listed. 


A.1 ACP-QIO Interface Driver 


Functions 

Arguments 

Modifiers 

IO$_CREATE 

IO$_ACCESS 

IO$_DEACCESS 

IO$_MODIFY 

IO$_DELETE 

IO$_ACPCONTROL 

PI - FIB descriptor 
address 

P2 - file name string 
address 

P3 - result string length 
address 

P4 - result string 

descriptor address 

P5 - attribute list 
address 

IO$M_CREATE’ 

lOSM-ACCESS 1 

IO$M_DELETE 2 

IO$M_DMOUNT 3 

IO$_MOUNT 

(none) 

(none) 

’Only for IO$_CREATE and IO$_ACCESS 

2 Only for IO$_CREATE and IO$_DELETE 

3 Only for IO$ACPCONTROL 


QIO Status Returns 


SS$_ACCONFLICT 

SS$_ACPV AFUL 

SS$_BADATTRIB 

SS$_BADCHKSUM 

SS$_BADFILEHDR 

SS$_BADFILENAME 

SSS—BADFILEVER 

SS$_B ADIRECT ORY 

SS$_BADPARAM 

SS$_BADQFILE 

SS$_BLOCKCNTERR 

SS$_CREATED 

SS$_DEVICEFULL 

SS$_DIRFULL 

SS$_DIRNOTEMPTY 

SS$_DUPDSKQUOT A 

SS$_DUPFILENAME 

SS$_ENDOFFILE 

SS$_EXBYTLM 

SS$_EXDISKQUOT A 

SS$_FCPREADERR 

SS$_FCPREWNDERR 

SS$_FCPSPACERR 

SS$_FCPWRITERR 

SS$_FILELOCKED 

SS$_FILENUMCHK 

SS$_FILEPURGED 

SS$_FILESEQCHK 

SS$_FILESTRUCT 

SS$_FILNOTEXP 

SS$_HEADERFULL 

SS$_IBCERROR’ 

SS$_IDXFILEFULL 

SS$_ILLCNTRFUNC 

SS$_NODISKQUOT A 

SS$_NOMOREFILES 


1 The second longword of the IOSB contains a job controller status code. 
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I/O Function Codes 

A.1 ACP-QIO Interface Driver 


QIO Status Returns 


SS$_NOPRIV 

SS$_NOQFILE 

SS$_NOSUCHFILE 

SS$_NOT APEOP 

SS$_NOTLABELMT 

SSS—NOTPRINTED 1 

SS$_NOT V OLSET 

SS$_OVRDSKQUOT A 

SS$_QFACTIVE 

SS$_QFNOT ACT 

SS$_SUPERSEDE 

SS$_T APEPOSLOST 

SS$_TOOMANYVER 

SS$_WRITLCK 

SS$_WRONGACP 


’The second longword of the IOSB contains a job controller status code. 


A.2 Card Reader Driver 


Functions 

Arguments 

Modifiers 

IO$_READLBLK 

IO$_READVBLK 

IO$_READPBLK 

PI - buffer address 

P2 - byte count 

IO$M_BINARY 

IO$M—PACKED 

IO$_SETMODE 

IO$_SETCHAR 

PI - characteristics 
buffer address 

(none) 

IO$SENSEMODE 

(none) 

(none) 


QIO Status Returns 


SS$ABORT SS$DAT AOVERUN SS$ENDOFFILE SS$NORMAL 


A. 3 Disk Drivers 


Functions 

Arguments 

Modifiers 

IO$_READVBLK 

PI - buffer address 

IO$M_INHSEEK’ 

IO$_READLBLK 

P2 - byte count 

IO$M_DAT ACHECK 2 

IO$_READPBLK 4 

P3 - disk address 

IO$M_DELDAT A 3 

IO$_WRITEVBLK 


IO$M_INHRETRY 

IO$_WRITELBLK 

I0$_WRITEPBLK 4 


IO$M_ERASE 6 

IO$_WRITECHECK 2 

P1 - buffer address 

P2 - byte count 

P3 - disk address 

(none) 


’Only for IO$READPBLK and IO$_WRITEPBLK (not for TU58, RX01, RX02, RB02 or 
RL02) 


2 Not for RX01 and RX02 
3 Only for IO$_WRITEPBLK on RX02 
4 Not for DSA disks 
5 Only for write functions 
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I/O Function Codes 

A.3 Disk Drivers 


Functions 

Arguments 

Modifiers 

IO$_SENSECHAR 

IO$_SENSEMODE 

IO$_PACKACK 

IO$_AVAILABLE 

IO$_UNLOAD 

(none) 

(none) 

IO$_SEARCH 

PI - read/write 
head position 

(none) 

I0$_SEEK 4 

PI - seek to 
specified 
cylinder 

(none) 

IO$_FORMAT 

PI - RX02 density 

(none) 

IO$_CREATE 

IO$_ACCESS 

IO$_DEACCESS 

IO$_MODIFY 

IO$_DELETE 

IO$_ACPCONTROL 

PI - FIB descriptor 
address 

P2 - file name string 
address 

P3 - result string 
length address 

P4 - result string 
descriptor 
address 

P5 - attribute list 
address 

IO$M_CREATE 6 

IO$M-ACCESS 6 

IO$M_DELETE 7 

IO$M_DMOUNT 8 

4 Not for DSA disks 



6 0nly for IO$_CREATE and IO$_ACCESS 

7 Only for IO$_CREATE and IO$_DELETE 

8 0nly for IO$ACPCONTROL 



QIO Status Returns 


SS$_ABORT 

SS$_CANCEL 

SS$_CTRLERR 

SS$_DAT ACHECK 

SS$_DAT AOVERUN 

SS$_DRVERR 

SS$_FORCEDERR 

SS$_FORMAT 

SS$_ILLIOFUNC 

SS$_IVADDR 

SS$_IVBUFLEN 

SS$_MEDOFL 

SS$_NONEXDRV 

SS$_NORMAL 

SS$_OPINCOMPL 

SS$_PARITY 

SSS—RCT 

SS$_RDDELD AT A 

SS$_TIMEOUT 

SS$_UNSAFE 

SS$_VOLINV 

SS$WASECC 

SS$WRITLCK 
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A.4 Laboratory Peripheral Accelerator Driver 


A.4 Laboratory Peripheral Accelerator Driver 


Functions 

Arguments 

Modifiers 

I0$_LOADMCODE 

PI - starting address of 

microcode to be loaded 

P2 - load byte count 

P3 - starting microprogram 
address to receive 
microcode 

(none) 

IO$_ST ARTMPROC 

(none) 

(none) 

10$_INITIALIZE 

PI - address of initialize 
command table 

P2 - initialize command 
buffer length 

(none) 

IO$_SETCLOCK 

P2 - mode of operation 

P3 - clock control and 
status 

P4 - real-time clock preset 

value (two's complement) 

(none) 

IO$_ST ARTDAT A 

PI - data transfer command 
table address 

P2 - data transfer command 
table length 

P3 - normal completion AST 
address 

P4 - overrun completion AST 
address 

IO$_SETEVF 


High-Level Language 

Subroutines 

Functions 

LPASADSWP 

Start A/D converter sweep. 

LPA$DASWP 

Start D/A converter sweep. 

LPASDISWP 

Start digital input sweep. 

LPASDOSWP 

Start digital output sweep. 

LPASLAMSKS 

Specify LPA11-K controller and digital mask words. 

LPA$SETADC 

Specify channel select parameters. 

LPASSETIBF 

Specify buffer parameters. 

LPASSTPSWP 

Stop sweep. 

LPA$CLOCKA 

Set Clock A rate. 

LPASCLOCKB 

Set Clock B rate. 

LPA$XRATE 

Compute clock rate and preset value. 

LPASIBFSTS 

Return buffer status. 

LPA$IGTBUF 

Return next available buffer. 

LPASINXTBF 

Alter buffer order. 

LPA$IWTBUF 

Return next buffer or wait. 
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I/O Function Codes 

A.4 Laboratory Peripheral Accelerator Driver 


High-Level Language 
Subroutines 

Functions 

LPA$RLSBUF 

Release buffer to LPA11-K. 

LPASRMVBUF 

Remove buffer from device queue. 

LPA$CVADF 

Convert A/D input to floating point. 

LPASFLT16 

Convert unsigned integer to floating point. 

LPASLOADMC 

Load microcode and initialize LPA11-K. 


QIO Status Returns 


SS$_ABORT 

SS$_CANCEL 

SS$_DEVACTIVE 

SS$_EXQUOT A 

SS$_INSFMEM 

SS$_MCNOTVALID 

SS$TIMEOUT 


SS$_BADPARAM 

SS$_CTRLERR 

SS$_DEVCMDERR 

SS$_INSFBUFDP 

SS$_IVBUFLEN 

SS$_PARITY 


SS$_BUFNOT ALIGN 

SS$_D AT ACHECK 

SS$_DEVREQERR 

SS$_INSFMAPREQ 

SS$_IVMODE 

SS$_POWERFAIL 


A.5 Line Printer Driver 


Functions 

Arguments 

Modifiers 

IO$_WRITEVBLK 

IO$_WRITELBLK 

IO$_WRITEPBLK 

PI - buffer address 

P2 - buffer size 

P3 - (ignored) 

P4 - carriage control 
specifier 1 

(none) 

IO$_SENSEMODE 

(none) 

(none) 

IO$_SETMODE 

IO$_SETCHAR 

PI - characteristics 
buffer address 

(none) 

’Only for IO$_WRITEVBLK and IO$_WRITELBLK 


QIO Status Returns 

SS$ABORT SS$ACCVIO SS$CANCEL SS$NORMAL 
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A.6 


Magnetic Tape Drivers 


Functions 

Arguments 

Modifiers 

IO$_READVBLK 

IO$_READLBLK 

IO$_READPBLK 

PI - buffer address 

P2 - byte count 

IO$M_DAT ACHECK 1 

IO$M_INHRETRY 

IO$M_REVERSE 3 

IO$_WRITEVBLK 

IO$_WRITELBLK 

IO$_WRITEPBLK 

PI - buffer address 

P2 - byte count 

io$m_datacheck’ 

IO$M_INHRETRY 

IO$M_INHEXTGAP 2 

IO$M_NOWAIT 8 

IO$M_ERASE 7 

IO$_SETMODE 

IO$_SETCHAR 

PI - characteristics buffer 
address 

P2 - characteristics buffer 
length 9 


IO$_CREATE 

IO$_ACCESS 

IO$_DEACCESS 

IO$_MODIFY 

IO$_ACPCONTROL 

PI - FIB descriptor 
address 

P2 - file name string 
address 

P3 - result string length 
address 

P4 - result string 

descriptor address 

P5 - attribute list address 

IO$M_CREATE 4 

IO$M—ACCESS 4 
IO$M_DMOUNT 5 

IO$_SKIPFILE 

PI - skip n tape marks 

IO$M_INHRETRY 

IO$M_NOWAIT 8 

IO$_SKIPRECORD 

PI - skip n blocks 

IO$M_INHRETRY 

IO$M_NOWAIT 8 

IO$_REWIND 

IO$_REWINDOFF 

IO$_UNLOAD 

(none) 

IO$M_INHRETRY 

IO$M_NOWAIT 

IO$_WRITEOF 

(none) 

IO$M_INHEXTGAP 2 

IO$M_INHRETRY 

IO$M_NOWAIT 8 

IO$_SENSEMODE 

IO$_SENSECHAR 

PI - characteristics 
buffer address 9 

P2 - characteristics 
buffer length 9 

IO$M_INHRETRY 


'Not for TS04 and TU80 


2 0nly for TE16, TU45, and TU77 
3 Not for TK50 

4 0nly for IO$_CREATE and IO$_ACCESS 
5 0nly for IO$_ACPCONTROL 

7 IO$M_ERASE takes no arguments; only for IO$_WRITELBLK and IO$_WRITEPBLK on 
TMSCP drives. 

8 0nly for TU81-Plus drives 

9 0nly for TMSCP drives 
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A.6 Magnetic Tape Drivers 


Functions 

Arguments 

Modifiers 

IO$_DSE 6 

IO$_PACKACK 

IO$_AVAILABLE 

(none) 

(none) 

6 Only for TU78, TU81, TA81, and TA78 


QIO Status Returns 


SS$_ABORT 

SS$_DAT ACHECK 

SS$_DRVERR 

SS$_ENDOFVOLUME 

SS$_MEDOFL 

SS$_OPINCOMPL 

SS$UNSAFE 


SS$_CANCEL 

SS$_D AT AOVERUN 

SS$_ENDOFFILE 

SS$_FORMAT 

SS$_NONEXDRV 

SS$_PARITY 

SS$VOLINV 


SS$_CTRLERR 

SS$_DEVOFFLINE 

SS$_ENDOFT APE 

SS$_ILLIOFUNC 

SS$_NORMAL 

SS$_TIMEOUT 

SS$WRITLCK 


A.7 Mailbox Driver 


Functions 

Arguments 

Modifiers 

IO$_READVBLK 

IO$_READLBLK 

IO$_READPBLK 

IO$_WRITEVBLK 

IO$_WRITELBLK 

IO$_WRITEPBLK 

PI - buffer 
address 

P2 - buffer size 

IO$M_NOW 

IO$M_ 

NORSWAIT 1 

IO$_WRITEOF 

(none) 

IO$M_NOW 

IO$_SETMODE!IO$M_READATTN 

IO$_SETMODE!IO$M_WRTATTN 

PI - AST address 

P2 - AST parameter 

P3 - access mode 

(none) 

IO$_SETMODE!IO$M_SETPROT 

P2 - volume 
protection 
mask 

(none) 

^nly for write functions 


QIO Status Returns 


SS$ABORT SS$BUFFEROVF SS$ENDOFFILE 

SS$NORMAL 
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A.8 Terminal Driver 


Functions 

Arguments 

Modifiers 

IO$_READVBLK 

PI - buffer address 

IO$M_NOECHO 

IO$_READLBLK 

P2 - buffer size 

IO$M_CVTLOW 

IO$_READPROMPT 

P3 - timeout 

IO$M_NOFILTR 


P4 - read terminator 

IO$M_TIMED 


block address 

IO$M_PURGE 


P5 - prompt string 

IO$M_DSABLMBX 


buffer address 

IO$M —TRMNOECHO 


P6 - prompt string 
buffer size 1 

IO$M_ESCAPE 

IO$_READVBLK 

PI - buffer address 

P2 - buffer size 

P3 - access mode to 
probe itemlist 

P4 - (zero) 

P5 - itemlist buffer 
address 

P6 - itemlist buffer 
size 

IO$M_EXTEND 2 

IO$_WRITEVBLK 

PI - buffer address 

IO$M_CANCTRLO 

IO$_WRITELBLK 

P2 - buffer size 

IO$M_ENABLMBX 

IO$_WRITEPBLK 

P3 - (ignored) 

IO$M_NOFORMAT 


P4 - carriage control 

IO$M_REFRESH 


specifier 3 

IO$M_BREAKTHRU 

IO$_SETMODE 

PI - characteristics 


IO$_SETCHAR 

buffer address 

P2 - characteristics 
buffer size 

P3 - speed specifier 

P4 - fill specifier 

P5 - parity flags 


IO$_SETMODE 

IO$_SETCHAR 

(none) 

IO$M_HANGUP 

IO$_SETMODE 

PI - buffer address 

P2 - buffer size 

IO$M_BRDCST 

IO$_SETMODE 

PI - AST service 

IO$M_CTRLCAST 

IO$_SETCHAR 

routine address 

P2 - AST parameter 

P3 - access mode to 
deliver AST 

IO$M _CTRLY AST 


^nly for IO$_READPROMPT 


2 0nly for itemlist read function. Do not specify with other modifiers. 
3 0nly for IO$_WRITELBLK and IO$_WRITEVBLK 
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A.8 Terminal Driver 


Functions 

Arguments 

Modifiers 

IO$_SETMODE 

IO$_SETCHAR 

PI - AST service 
routine address 

P2 - character mask 
address 

P3 - access mode to 
deliver AST 

IO$M_OUTBAND 

IO$M_TT_ABORT 4 

IO$M_INCLUDE 4 

IO$_SETMODE 

IO$_SETCHAR 

PI - address of 

control signals 

IO$M_SET_MODEM 5 

IO$M_MAINT 

IO$_SETMODE 

IO$_SETCHAR 

(none) 

IO$M_LOOP 5 

IO$M_UNLOOP 5 

IO$M_MAINT 

IO$_TTY_PORT 


IO$M_LT_CONNECT 

IO$M_LT_DISCON 

IO$_TTY_PORT 

PI - item list 6 
address 

P2 - queued status 

IO$M_LT_MAP_PORT 

IO$_TTY_PORT 

PI - service name 
descriptor 
address 

P2 - service rating 

IO$M_LT_RATING 

IO$_SENSEMODE 

IO$_SENSECHAR 

PI - characteristics 
buffer address 

P2 - characteristics 
buffer size 

IO$M —TYPE AHDCNT 

IO$_SENSEMODE 

IO$_SENSECHAR 

PI - address of input 
modem signal 
block 

IO$M —RD—MODEM 

IO$_SENSEMODE 

PI - buffer address 

P2 - buffer size 

IO$M_BRDCST 


4 Only with IO$M_OUTBAND 


5 Only with IO$M_MAINT 

6 ltem list: IO$V_LT_MAP_NODNAM, IO$V_LT_MAP_PORNAM, IO$V_LT_MAP_SRVNAM, 
IO$V LT MAP LNKNAM, and IO$V LT MAP NETADR. 


QIO Status Returns 


SS$_ABORT 

SS$_CANCEL 

SS$_CONTROLY 

SS$_NORMAL 

SS$TIMEOUT 


SS$_BADESCAPE 
SS$_CONTROLC 
SS$_D AT AOVERUN 
SS$_PARITY 


SS$_BADPARAM 
SS$_CONTROLO 
SS$_INCOMPAT 
SS$_PARTESCAPE 


A-9 














c 


B Tables 


B.1 




DEC Multinational Character Set 

Table B-l lists the DEC Multinational Character Set. The DEC Multinational 
Character set is an eight-bit character set with 256 characters. The first 128 
characters in the set correspond to the ASCII character set. The VAX EDT 
Reference Manual lists the graphics for these characters and describes how to 
enter them from various types of terminals. 


Table B-1 DEC Multinational Character Set 


Hex 

Code 

Octal 

Code 

Decimal 

Code 

Char or 
Abbrev. 

Description 

ASCII Control Characters 1 

00 

000 

000 

NUL 

null character 

01 

001 

001 

SOH 

start of heading (CTRL/A) 

02 

002 

002 

STX 

start of text (CTRL/B) 

03 

003 

003 

ETX 

end of text (CTRL/C) 

04 

004 

004 

EOT 

end of transmission (CTRL/D) 

05 

005 

005 

ENQ 

enquiry (CTRL/E) 

06 

006 

006 

ACK 

acknowledge (CTRL/F) 

07 

007 

007 

BEL 

bell (CTRL/G) 

08 

010 

008 

BS 

backspace (CTRL/H) 

09 

Oil 

009 

HT 

horizontal tabulation (CTRL/I) 

OA 

012 

010 

LF 

line feed (CTRL/J) 

OB 

013 

Oil 

VT 

vertical tabulation (CTRL/K) 

OC 

014 

012 

FF 

form feed (CTRL/L) 

OD 

015 

013 

CR 

carriage return (CTRL/M) 

OE 

016 

014 

SO 

shift out (CTRL/N) 

OF 

017 

015 

SI 

shift in (CTRL/O) 

10 

020 

016 

DLE 

data link escape (CTRL/P) 

11 

021 

017 

DC1 

device control 1 (CTRL/Q) 

12 

022 

018 

DC2 

device control 2 (CTRL/R) 

13 

023 

019 

DC3 

device control 3 (CTRL/S) 

14 

024 

020 

DC4 

device control 4 (CTRL/T) 

15 

025 

021 

NAK 

negative acknowlege (CTRL/U) 

16 

026 

022 

SYN 

synchronous idle (CTRL/V) 


'The ALTMODE and DELETE characters (decimal 125, 126, and 127) are also control 


characters. 


B-1 










Tables 

B.1 DEC Multinational Character Set 


Table B-1 (Cont.) DEC Multinational Character Set 


Hex 

Code 

Octal 

Code 

Decimal 

Code 

Char or 
Abbrev. 

Description 

ASCII Control Characters 1 

17 

027 

023 

ETB 

end of transmission block 
(CTRL/W) 

18 

030 

024 

CAN 

cancel (CTRL/X) 

19 

031 

025 

EM 

end of medium (CTRL/Y) 

1A 

032 

026 

SUB 

substitute (CTRL/Z) 

IB 

033 

027 

ESC 

escape 

1C 

034 

028 

FS 

file separator 

ID 

035 

029 

GS 

group separator 

IE 

036 

030 

RS 

record separator 

IF 

037 

031 

US 

unit separator 


ASCII Special and Numeric Characters 


20 

040 

032 

SP 

space 

21 

041 

033 

! 

exclamation point 

22 

042 

034 

II 

quotation marks (double quote) 

23 

043 

035 

# 

number sign 

24 

044 

036 

$ 

dollar sign 

25 

045 

037 

% 

percent sign 

26 

046 

038 

& 

ampersand 

27 

047 

039 

/ 

apostrophe (single quote) 

28 

050 

040 

( 

opening parenthesis 

29 

051 

041 

) 

closing parenthesis 

2A 

052 

042 

* 

asterisk 

2B 

053 

043 

+ 

plus 

2C 

054 

044 

i 

comma 

2D 

055 

045 

~ 

hyphen or minus 

2E 

056 

046 


period or decimal point 

2F 

057 

047 

/ 

slash 

30 

060 

048 

0 

zero 

31 

061 

049 

1 

one 

32 

062 

050 

2 

two 

33 

063 

051 

3 

three 

34 

064 

052 

4 

four 

35 

065 

053 

5 

five 


1- The ALTMODE and DELETE characters (decimal 125, 126, and 127) are also control 
characters. 
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Table B-1 (Cont.) DEC Multinational Character Set 


Hex 

Code 

Octal 

Code 

Decimal 

Code 

Char or 
Abbrev. 

Description 

ASCII Special and Numeric Characters 

36 

066 

054 

6 

six 

37 

067 

055 

7 

seven 

38 

070 

056 

8 

eight 

39 

071 

057 

9 

nine 

3A 

072 

058 


colon 

3B 

073 

059 

# 

semicolon 

3C 

074 

060 

< 

less than 

3D 

075 

061 

= 

equals 

3E 

076 

062 

> 

greater than 

3F 

077 

063 

? 

question mark 


ASCII Alpha Characters 


40 

100 

064 

@ 

commercial at sign 

41 

101 

065 

A 

uppercase A 

42 

102 

066 

B 

uppercase B 

43 

103 

067 

C 

uppercase C 

44 

104 

068 

D 

uppercase D 

45 

105 

069 

E 

uppercase E 

46 

106 

070 

F 

uppercase F 

47 

107 

071 

G 

uppercase G 

48 

110 

072 

H 

uppercase H 

49 

111 

073 

1 

uppercase 1 

4A 

112 

074 

J 

uppercase J 

4B 

113 

075 

K 

uppercase K 

4C 

114 

076 

L 

uppercase L 

4D 

115 

077 

M 

uppercase M 

4E 

116 

078 

N 

uppercase N 

4F 

117 

079 

0 

uppercase 0 

50 

120 

080 

P 

uppercase P 

51 

121 

081 

Q 

uppercase Q 

52 

122 

082 

R 

uppercase R 

53 

123 

083 

S 

uppercase S 

54 

124 

084 

T 

uppercase T 

55 

125 

085 

U 

uppercase U 

56 

126 

086 

V 

uppercase V 

57 

127 

087 

w 

uppercase W 
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Table B-1 (Cont.) DEC Multinational Character Set 


Hex 

Octal 

Decimal 

Char or 


Code 

Code 

Code 

Abbrev. 

Description 

ASCII Alpha Characters 

58 

130 

088 

X 

uppercase X 

59 

131 

089 

Y 

uppercase Y 

5A 

132 

090 

Z 

uppercase Z 

5B 

133 

091 

[ 

left bracket 

5C 

134 

092 

\ 

backslash 

5D 

135 

093 

1 

right bracket 

5E 

136 

094 

* 

circumflex 

5F 

137 

095 

_ 

underscore 

60 

140 

096 

\ 

grave accent 

61 

141 

097 

a 

lowercase a 

62 

142 

098 

b 

lowercase b 

63 

143 

099 

c 

lowercase c 

64 

144 

100 

d 

lowercase d 

65 

145 

101 

e 

lowercase e 

66 

146 

102 

f 

lowercase f 

67 

147 

103 

g 

lowercase g 

68 

150 

104 

h 

lowercase h 

69 

151 

105 

i 

lowercase i 

6A 

152 

106 

j 

lowercase j 

6B 

153 

107 

k 

lowercase k 

6C 

154 

108 

1 

lowercase 1 

6D 

155 

109 

m 

lowercase m 

6E 

156 

110 

n 

lowercase n 

6F 

157 

111 

o 

lowercase o 

70 

160 

112 

P 

lowercase p 

71 

161 

113 

q 

lowercase q 

72 

162 

114 

r 

lowercase r 

73 

163 

115 

s 

lowercase s 

74 

164 

116 

t 

lowercase t 

75 

165 

117 

u 

lowercase u 

76 

166 

118 

V 

lowercase v 

77 

167 

119 

w 

lowercase w 

78 

170 

120 

X 

lowercase x 

79 

171 

121 

y 

lowercase y 

7A 

172 

122 

z 

lowercase z 

7B 

173 

123 

{ 

left brace 
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Table B-1 (Cont.) DEC Multinational Character Set 

Hex Octal Decimal Char or 

Code Code Code Abbrev. Description 


ASCII Alpha Characters 


7C 

174 

124 

1 

vertical line 

7D 

175 

125 

} 

right brace (ALTMODE) 

7E 

176 

126 


tilde (ALTMODE) 

7F 

177 

127 

DEL 

rubout (DELETE) 

80 

200 

128 

— 

[reserved] 

81 

201 

129 

— 

[reserved] 

82 

202 

130 

— 

[reserved] 

83 

203 

131 

— 

[reserved] 

84 

204 

132 

IND 

index 

85 

205 

133 

NEL 

next line 

86 

206 

134 

SSA 

start of selected area 

87 

207 

135 

ESA 

end of started area 

88 

210 

136 

HTS 

horizontal tab set 

89 

211 

137 

HTJ 

horizontal tab set with 
justification 

8A 

212 

138 

VTS 

vertical tab set 

8B 

213 

139 

PLD 

partial line down 

8C 

214 

140 

PLU 

partial line up 

8D 

215 

141 

Rl 

reverse index 

8E 

216 

142 

SS2 

single shift 2 

8F 

217 

143 

SS3 

single shift 3 

90 

220 

144 

DCS 

device control string 

91 

221 

145 

PU1 

private use 1 

92 

222 

146 

PU2 

private use 2 

93 

223 

147 

STS 

set transmit state 

94 

224 

148 

CCH 

cancel character 

95 

225 

149 

MW 

message waiting 

96 

226 

150 

SPA 

start of protected area 

97 

227 

151 

EPA 

end of protected area 

98 

230 

152 

— 

[reserved] 

99 

231 

153 

— 

[reserved] 

9A 

232 

154 

— 

[reserved] 

9B 

233 

155 

CSI 

control sequence introducer 

9C 

234 

156 

ST 

string terminator 

9D 

235 

157 

OSC 

operating system command 

9E 

236 

158 

PM 

privacy message 
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Table B-1 (Cont.) DEC Multinational Character Set 


Hex 

Code 

Octal 

Code 

Decimal 

Code 

Char or 
Abbrev. 

Description 



ASCII Alpha Characters 

9F 

237 

159 

APC 

application 

AO 

240 

160 

— 

[reserved] 

A1 

241 

161 

1 

inverted exclamation point 

A2 

242 

162 

e 

cent sign 

A3 

243 

163 

£ 

pound sign 

A4 

244 

164 

— 

[reserved] 

A5 

245 

165 

¥ 

yen sign 

A6 

246 

166 

— 

[reserved] 

A7 

247 

167 

§ 

section sign 

A8 

250 

168 

H 

general currency sign 

A9 

251 

169 

© 

copyright sign 

AA 

252 

170 

a 

feminine ordinal indicator 

AB 

253 

171 

« 

angle quotation mark left 

AC 

254 

172 

— 

[reserved] 

AD 

255 

173 

— 

[reserved] 

AE 

256 

174 

— 

[reserved] 

AF 

257 

175 

— 

[reserved] 

BO 

260 

176 

o 

degree sign 

B1 

261 

177 

± 

plus/minus sign 

B2 

262 

178 

2 

superscript 2 

B3 

263 

179 

3 

superscript 3 

B4 

264 

180 

— 

[reserved] 

B5 

265 

181 


micro sign 

B6 

266 

182 

1 

paragraph sign, pilcrow 

B7 

267 

183 

• 

middle dot 

B8 

270 

184 

— 

[reserved] 

B9 

271 

185 

1 

superscript 1 

BA 

272 

186 

£ 

masculine ordinal indicator 

BB 

273 

187 

» 

angle quotation mark right 

BC 

274 

188 

% 

fraction one-quarter 

BD 

275 

189 

Vi 

fraction one-half 

BE 

276 

190 

— 

[reserved] 

BF 

277 

191 

6 

inverted question mark 

CO 

300 

192 

A 

uppercase A with grave 
accent 

Cl 

301 

193 

A 

uppercase A with acute 
accent 
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Table B-1 (Cont.) DEC Multinational Character Set 

Hex Octal Decimal Char or 

Code Code Code Abbrev. Description 


ASCII Alpha Characters 


C2 

302 

194 

A 

uppercase A with circumflex 

C3 

303 

195 

A 

uppercase A with tilde 

C4 

304 

196 

A 

uppercase A with umlaut, 
(diaeresis) 

C5 

305 

197 

A 

uppercase A with ring 

C6 

306 

198 

/E 

uppercase AE diphthong 

C7 

307 

199 

Q 

uppercase C with cedilla 

C8 

310 

200 

E 

uppercase E with grave 
accent 

C9 

311 

201 

E 

uppercase E with acute 
accent 

CA 

312 

202 

E 

uppercase E with circumflex 

CB 

313 

203 

E 

uppercase E with umlaut, 
(diaeresis) 

CC 

314 

204 

i 

uppercase 1 with grave 
accent 

CD 

315 

205 

i 

uppercase 1 with acute 
accent 

CE 

316 

206 

i 

uppercase 1 with circumflex 

CF 

317 

207 

! 

uppercase 1 with umlaut, 
(diaeresis) 

DO 

320 

208 

— 

[reserved] 

D1 

321 

209 

N 

uppercase N with tilde 

D2 

322 

210 

6 

uppercase 0 with grave 
accent 

D3 

323 

211 

6 

uppercase 0 with acute 
accent 

D4 

324 

212 

0 

uppercase 0 with circumflex 

D5 

325 

213 

6 

uppercase 0 with tilde 

D6 

326 

214 

6 

uppercase 0 with umlaut, 
(diaeresis) 

D7 

327 

215 

CE 

uppercase OE ligature 

D8 

330 

216 

0 

uppercase 0 with slash 

D9 

331 

217 

0 

uppercase U with grave 
accent 

DA 

332 

218 

0 

uppercase U with acute 
accent 

DB 

333 

219 

0 

uppercase U with circumflex 
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Table B-1 (Cont.) DEC Multinational Character Set 

Hex Octal Decimal Char or 

Code Code Code Abbrev. Description 


ASCII Alpha Characters 


DC 

334 

220 

0 

uppercase U with umlaut, 
(diaeresis) 

DD 

335 

221 

Y 

uppercase Y with umlaut, 
(diaeresis) 

DE 

336 

222 

— 

[reserved] 

DF 

337 

223 

8 

German lowercase sharp s 

EO 

340 

224 

a 

lowercase a with grave 
accent 

El 

341 

225 

a 

lowercase a with acute 
accent 

E2 

342 

226 

a 

lowercase a with circumflex 

E3 

343 

227 

a 

lowercase a with tilde 

E4 

344 

228 

a 

lowercase a with umlaut, 
(diaeresis) 

E5 

345 

229 

a 

lowercase a with ring 

E6 

346 

230 

ae 

lowercase ae diphthong 

E7 

347 

231 

S 

lowercase c with cedilla 

E8 

350 

232 

e 

lowercase e with grave 
accent 

E9 

351 

233 

e 

lowercase e with acute 
accent 

EA 

352 

234 

e 

lowercase e with circumflex 

EB 

353 

235 

e 

lowercase e with umlaut, 
(diaeresis) 

EC 

354 

236 

i 

lowercase i with grave 
accent 

ED 

355 

237 

\ 

lowercase i with acute 
accent 

EE 

356 

238 

i 

lowercase i with circumflex 

EF 

357 

239 

T 

lowercase i with umlaut, 
(diaeresis) 

FO 

360 

240 

— 

[reserved] 

FI 

361 

241 

n 

lowercase n with tilde 

F2 

362 

242 

6 

lowercase o with grave 
accent 

F3 

363 

243 

6 

lowercase o with acute 
accent 

F4 

364 

244 

6 

lowercase o with circumflex 

F5 

365 

245 

6 

lowercase o with tilde 
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Table B-1 (Cont.) DEC Multinational Character Set 


Hex 

Code 

Octal 

Code 

Decimal 

Code 

Char or 
Abbrev. 

Description 

ASCII Alpha Characters 

F6 

366 

246 

6 

lowercase o with umlaut, 
(diaeresis) 

F7 

367 

247 

ce 

lowercase oe ligature 

F8 

370 

248 

0 

lowercase o with slash 

F9 

371 

249 

u 

lowercase u with grave 
accent 

FA 

372 

250 

u 

lowercase u with acute 
accent 

FB 

373 

251 

u 

lowercase u with circumflex 

FC 

374 

252 

u 

lowercase u with umlaut, 
(diaeresis) 

FD 

375 

253 

V 

lowercase y with umlaut, 
(diaeresis) 

FE 

376 

254 

— 

[reserved] 

FF 

377 

255 

— 

[reserved] 


B.2 Terminal Sequences and Modes 

Table B-2 lists the valid ANSI and DIGITAL-private escape sequences for 
terminals that have the TT2$M_ANSICRT, TT2$M_DECCRT, TT2$M_AVO, 
TT2$M_EDIT, and TT2$M_BLOCK characteristics (see Section 8). Table B-2 
also lists assumed and selectable ANSI modes and selectable DIGITAL-private 
modes. Only the names of the escape sequences and modes are listed (for 
more information see the specific VT100-, VT200-, or VT300- family user's 
guide). Unless otherwise noted, the operation of escape sequences and modes 
is identical to the particular VT100-, VT200-, or VT300- family terminals that 
implement these features. 
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Table B-2 Sequences and Modes 


Name 

Valid Parameters 

ANSICRT 

DECCRT AVO 

EDIT 

BLOCK 1 

ANSI-Defined Escape Sequences 

CPR 

All 

X 

X 



CUB 

All 

X 

X 



CUD 

All 

X 

X 



CUF 

All 

X 

X 



CUP 

All 

X 

X 



CUU 

All 

X 

X 



DSR 

0,3,5,6 

X 

X 



ED 

0,1,2 

X 

X 



EL 

0,1,2 

X 

X 



HVP 

All 

X 

X 



IND 


X 

X 



NEL 


X 

X 



Rl 


X 

X 



RIS 


X 

X 



SCS 

UK,ASCII,0 

X 




SCS 

UK,ASCII 

X 

X 



SGR 

0,4,7 

X 

X 



SGR 

0,1,4,5,7 


X 



DA 

Terminal specific 


X 



HTS 



X 



RM 

Class specific 


X 



SM 

Class specific 


X 



TBC 

0,3 


X 



DCH 

All 



X 

X 

DL 

All 



X 

X 

IL 

All 



X 

X 

DIGITAL-Private Escape Sequences 

DECDHDL 

2,3 


X 



DECDWL 

6 


X 



DECKPAM 



X 



DECKPNM 



X 



DECRC 

8 


X 



DECSC 

7 


X 



DECSTBM 

All 


X 




’Terminal characteristics. Prefix is TT2$M_ 
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Table B- 

-2 (Cont.) Sequences and Modes 



Name 

Valid Parameters ANSICRT DECCRT AVO 

EDIT 

BLOCK 1 

DIGITAL-Private Escape Sequences 

DECSWL 

5 x 



DECPRO 

0,1,4,5,7,254 


X 

DECTTC 

0,1 


X 

DECXMIT 

5 


X 

ANSI Selectable Modes (Set with ANSI SM/RM) 

IRM 

4 

X 

X 

GATM 

1 

X 

X 

ERM 

6 


X 

TTM 

16 


X 


DIGITAL-Private Selectable Modes (Set with ANSI SM/RM) 


DECCKM 

1 

X 


DECANM 

2 

X 


DECCOLM 

3 

X 


DECSCLM 

4 

X 


DECSCNM 

5 

X 


DECOM 

6 

X 


DECAWM 

7 

X 


DECARM 

8 

X 


DECEDM 

10 


X 

DECEKEM 

16 


X 

DECLTM 

11 


X 

DECSCFDM 

13 


X 

DECTEM 

14 


X 


ANSI Assumed Modes 


CRM 

Reset 

Reset 


EBM 

Reset 

Reset 


ERM 

Set 

Set 

2 

FEAM 

Reset 

Reset 


FETM 

Reset 

Reset 


GATM 

N/A 

N/A 

2 

HEM 

N/A 

N/A 



terminal characteristics. Prefix is TT2$M_ 
2 Selectable mode 


B—11 















Tables 

B.2 Terminal Sequences and Modes 


Table B-2 (Cont.) Sequences and Modes 

Name Valid Parameters ANSICRT DECCRT AVO EDIT BLOCK 1 

ANSI Assumed Modes 


IRM 

Reset 

Reset 

KAM 

Reset 

Reset 

MATH 

N/A 

N/A 

PUM 

Reset 

Reset 

SATM 

N/A 

N/A 

SRTM 

Reset 

Reset 

TSM 

Reset 

Reset 

TTM 

N/A 

N/A 

VEM 

N/A 

N/A 


terminal characteristics. Prefix is TT2$M_ 
2 Selectable mode 
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A 


ACP control function® 1-34 
disk quotas® 1-37 
magnetic tape positioning® 1-36 
miscellaneous disk® 1-36 
quota file transfer block® 1-37 
ACP function® 1-2 
arguments® 1-2 
attributes • 1 -18 to 1 -20 
IO$_ACCESS® 1-9, 1-11, 1-17,1-29 
IO$_ACPCONTROL® 1-9, 1-34 
IO$_CREATE® 1-11, 1-13, 1-17,1-25 
IO$_DE ACCESS® 1-15, 1-17, 1-31 
IO$_DELETE® 1-9, 1-33 
IO$_MODIFY® 1-9, 1-13, 1-15, 1-17, 1-32 
IO$_MOUNT • 1-34 
major® 1-25 
ACP-QIO interface 

access file function® 1-29 
access subfunction® 1-11 
ACP control function® 1-34 
ANSI standard® 1-2, 1-36 
arguments® 1-2 

disk quota® 1-38 
attribute control block® 1-17 
attributes • 1 -18 to 1 -20 
attributes statistics block® 1-23 
BLISS-32 programming® 1-2 
create file function® 1-25 
disk® 1-27 
magnetic tape® 1-28 
deaccess file function® 1-31 
delete file function® 1-33 
description® 1-1 
directory entries® 1-11, 1-28 
FIB (file information block)® 1-3 

See also FIB (file information block) 
file characteristics® 1-20 
function codes® A-1 
function modifiers® 1-2 

IO$M_ACCESS® 1 — 11, 1-25, 1-28, 1-29 
IO$M_CREATE® 1-25, 1-27, 1-28, 1-29 
IO$M_DELETE® 1-25, 1-27, 1-33 
IO$M_DMOUNT® 1-34, 1-36 


ACP-QIO interface (cont'd.) 

I/O operations® 1-1 
I/O status block® 1-40 
record attributes area® 1-21 
values® 1-22 

serious exception (EOT)® 1-26, 1-30, 1-36 
status returns® A-1 
VAX MACRO programming® 1-1 
XQP (extended QIO processor)® 1-1 
ACP subfunction® 1-8 
access® 1-11 
directory lookup® 1-9 
extend® 1-13, 1-40 
read/write attributes® 1-17 
truncate® 1-15 
ALTMODE key®8-21 
ANSI escape sequence ®B-9 
Application programs 

connecting to LAT ports • 8-49 
Argument 

device- or function-dependent® 1-2 
list®A-1 to A-9 
LPA11 -K subroutine • 4-15 
ASCII (8-bit) code®2-8 
ASCII character set 

See DEC Multinational Character Set 
AST (asynchronous system trap) 

quota®3-18, 4-13, 6-8,7-5,8-44 
Attention AST 
mailbox® 7-9 
terminal • 8-44 


B 


Batch job command procedure 
using a card reader®2-2 
Baud rate 

terminal® 8-42 
BOT (beginning-of-tape) 

See Magnetic tape, BOT marker 
Broadcast message®8-17, 8-21, 8-23, 8-48 
Buffered I/O quota®3-18, 6-8, 7-5 
Buffer overrun 

with LPA11-K®4-10 
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Index 


C 


Card reader 

card punch combinations®2-1 
026 card reader code *2-2, 2-8 
029 card reader code *2-2, 2-8 
code*2-8 

device characteristics • 2-5 
driver® 2-1 

end-of-file status • 2-2 
error recovery • 2-4 
failure categories • 2-4 
features® 2-1 

for batch job command procedures • 2-2 
function codes® 2-5, A-2 
function modifiers 

IO$M_BINARY • 2-1, 2-6 
IO$M_PACKED® 2-1, 2-6 
I/O functions 

IO$_RE ADLBLK • 2-6 
IO$_RE ADPBLK • 2-6 
IO$_RE ADVBLK • 2-6 
IO$_SENSEMODE • 2-7 
IO$_SETCHAR®2-10 
IO$_SETMODE • 2-8 
I/O status block®2-11 
read function • 2-6 
read modes®2-1 
sense mode function®2-7 
set mode function • 2-7 
set translation mode • 2-2 
status returns® A-2 
supported device®2-1 
SYS$GETDVI returns®2-5 
Carriage control 
line printer®5-6 
terminal® 8-38 
Character 

formatting on line printer®5-2 
terminal terminator®8-29 
Character set 

See DEC Multinational Character Set 
terminal lowercase®8-21 
Clock rate 

with LPA11 -K • 4-9 
CONNECT command®8-17 
Console disk 

See RX01 console disk 
Console terminal®8-1 


Control character 
list • B— 1 

terminal®8-4 to 8-7, 8-10 
Control sequence 
terminal® 8-9 
Create file function® 1-25 

directory entry creation® 1-28 
CTRL/x 

See Terminal, control characters 


D 


Data buffer, LPA11-K®4-12 
Data check 

disk®3-10, 3-22, 3-23 
magnetic tape • 6-4, 6-12, 6-13 
Data security erase 
magnetic tape • 6-21 
Data transfer command table 
LPA11-K®4-10 
Data transfer start command 
LPA11 -K • 4— 11 
Data transfer stop command 
LPA11-K®4-13 
Data underrun/overrun 
with LPA11-K®4-10 
Deaccess file function® 1-31 
DEC026 card reader code®2-2, 2-8 
DEC029 card reader code®2-2, 2-8 
DEC Multinational Character Set®B-1 
Delete file function® 1-33 
DELETE key®8-4 
Device characteristics 
card reader®2-5 
disk® 3-16 
line printer®5-3 
LPA11-K device®4-4 
magnetic tape®6-6 
mailbox® 7-4 
terminal® 8-19 
DHU11 device® 8-1 
DHV11 device® 8-1 
Dial-up line®8-12 

DIGITAL-private escape sequence ®B-9 
Direct I/O quota®3-18, 6-8 
Directory entry 
creation® 1-28 
protection® 1-11 

Directory lookup subfunction® 1-9 
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Directory lookup subfunction (cont'd.) 

directory entry protection* 1-11 
DISCONNECT command *8-17 
Disk 

See also DSA disk 

ACP control function* 1-36 

ACP operation 

creating file* 1-27 
deaccessing file* 1-32 
available function *3-26 
Backup Utility *3-15 
data check *3-10, 3-22, 3-23 
device characteristics *3-16 
driver *3-1 

VAXstation 2000 and MicroVAX 2000 
3-15 

dual porting • 3-8 
DSA disks *3-10 
restrictions for use • 3-9 
error recovery *3-11 
features *3-7 
file attributes *3-10 
function codes *3-18, A-2 
function modifiers 

IO$M_DATACHECK *3-10, 3-22, 3-2 
IO$M_DELDAT A • 3-23 
I0$M_ERASE • 3-20, 3-24 
IO$M_INHRETRY *3-12, 3-23 
HSC50 controller *3-3 
I/O functions *3-17 

See also ACP-QIO interface 
arguments *3-19 to 3-22 
IO$_ACPCONTROL • 1-36 
IO$_AVAILABLE • 3-26 
IO$_FORMAT • 3-24 
IO$_PACKACK • 3-25 
IO$_READLBLK • 3-22 
IOS—READPBLK • 3-22 
IO$_RE ADVBLK • 3-22 
IOS—SEARCH • 3-25 
IO$_SEEK*3-26 
IO$_SENSECHAR • 3-24 
IO$_SENSEMODE • 3-24 
IO$_UNLOAD • 3-25 
IO$_WRITECHECK • 3-26 
IO$_WRITELBLK • 3-23 
IO$_WRITEPBLK • 3-23 
IO$_WRITEVBLK • 3-23 
I/O status block *3-27 
offset recovery *3-11 
pack acknowledge function *3-25 


Disk (cont'd.) 

port access mode • 3-8 
port selection • 3-8 
programming example *3-27 
quotas* 1-37 to 1-39, 3-18 
RCT (replacement and caching table) *3-14 
read function • 3-22 
search function • 3-25 
sector translation *3-12 
seek operations *3-11, 3-26 
sense mode function • 3-24 
set density function • 3-24 
skip sectoring *3-12 
status returns • A-3 
supported devices *3-1 to 3-7 
SYS$GETDVI returns *3-16 
TU58 magnetic tape*3-7, 3-11, 3-22, 3-23, 
3-25, 3-26 

UDA50 disk adapter *3-2 
unload function *3-25 
use with Verify Utility *3-14, 3-15 
VAXstation 2000 and MicroVAX 2000 driver* 
3-15 

write check function *3-26 
write function • 3-23 
Diskette • 3-6 

DISMOUNT command* 1-36 
DMB32 device *8-1 
DMF32 device *8-1 
DMZ32 device *8-1 
Driver 

card reader *2-1 
disk *3-1 
LAT port *8-1 
line printer *5-1 
LPA11-K device *4-1 
magnetic tape *6-1 
mailbox *7-1 
terminal *8-1 

VAXstation 2000 and MicroVAX 2000 disk* 
3-15 

DSA (DIGITAL Storage Architecture) 

See DSA disk 

DSA disk *3-1, 3-10, 3-13 to 3-15 
See also Disk 
bad block *3-14, 3-15 
bad block replacement *3-14, 3-15 
forced error *3-14 
forced error flag *3-15 
use with Verify Utility *3-14, 3-15 
Dual-ported disk *3-8 
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Dual-ported disk (cont'd.) 
DSA disk *3-10 
restrictions for use*3-9 
Duplex mode 

See also Half-duplex mode 
terminal *8-11 
DZ11 device *8-1 
DZ32 device *8-1 
DZV11 device *8-1 


E 


End-of-file 
See EOF 
End-of-tape 
See EOT 
End-of-volume 

detection on magnetic tape *6-15 
EOF (end-of-file) 
status 

card reader *2-2 
magnetic tape *6-12 
write mailbox message *7-8 
EOJ command 

in card reader batch job • 2-2 
EOT (end-of-tape) 
status 

magnetic tape *6-12, 6-14, 6-16 
Error recovery 
disk *3-11 
line printer *5-3 
magnetic tape *6-5 
Escape sequence 
ANSI • B-9 

DIGIT AL-private • B-9 
terminal *8-8, 8-20 
Extend subfunction* 1-13 


F 


FIB (file information block)* 1-3 
See also ACP function 
access control *1-11 
contents • 1-5 to 1-8 
descriptor* 1-2, 1-3 
directory lookup • 1 -9 
disk quota* 1-37 to 1-39 


FIB (file information block) (cont'd.) 
extend control* 1-13 
format • 1 -5 
IO$_ACCESS* 1-30 
IO$_ACPCONTROL • 1-35 to 1-39 
IO$_CRE ATE • 1-25 
I0$_DE ACCESS *1-32 
IO$_DELETE • 1-34 
IO$_MODIFY • 1-33 
truncate control* 1-16 
File characteristics 

ACP-QIO attributes • 1 -20 
Floppy disk 
See Diskette 
Form feed 

line printer *5-4 
mechanical • 5-4 
terminal • 8-21 
Full-duplex mode *8-11 
Function code 

See also I/O function 
IO$_ACCESS* 1-29 
IO$_ACPCONTROL • 1-34, 6-10 
IO$_AVAILABLE • 3-26, 6-21 
I0$_CRE ATE *1-25 
IO$_DEACCESS*1-31 
I0$_DELETE • 1-33 
IO$_DSE•6-21 
IO$_FORM AT • 3-24 

10$_INITIALIZE • 4-8 

IO$_LOADMCODE • 4-7 
IO$_MODIFY • 1-32 
IO$_PACKACK • 3-25 

IO$_READLBLK • 2-6, 3-22, 6-12, 7-6, 8-27 
IO$_READPBLK • 2-6, 3-22, 6-12, 7-6 
IO$_READPROMPT • 8-27 
IO$_READVBLK • 2-6, 3-22, 6-12, 7-6, 8-27 
IO$_RE WIND *6-14 
IO$_RE WINDOFF *6-16 
I0$_SEARCH • 3-25 
IO$_SEEK*3-26 
IO$_SENSECHAR • 3-24, 8-53 
IO$_SENSEMODE • 2-7, 3-24, 5-8, 6-16, 
8-53 

I0$_SETCHAR *2-10, 5-9, 6-17, 8-40 
IO$_SETCLOCK•4-9 
IO$_SETMODE*2-8, 5-9, 6-17,8-40 
IO$_SKIPFILE *6-14 
IO$_SKIPRECORD *6-15 
IO$_ST ARTD AT A *4-10 
I0$_UNL0AD • 3-25, 6-16 
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Function code (cont’d.) 

IO$_WRITECHECK • 3-26 
IO$_WRITELBLK • 3-23, 5-5, 6-13, 7-7, 
8-37 

IO$_WRITEOF *6-16 
IO$_WRITEPBLK • 3-23, 5-5, 6-13, 7-7, 
8-37 

IO$_WRITEVBLK • 3-23, 5-5, 6-13, 7-7, 
8-37 

list of • A-1 to A-9 
Function modifier 

IO$M_ACCESS* 1-25, 1-29, 6-9 
IO$M_BINARY • 2-6 
IO$M_BRDCST • 8-49, 8-56 
IO$M_BREAKTHRU*8-11, 8-37 
IO$M_CANCTRLO • 8-5, 8-37 
IO$M_CREATE *1-25, 1-29, 6-9 
IO$M _CTRLC AST • 8-44 
IO$M_CTRLYAST*8-6, 8-44 
IO$M_CVTLOW • 8-28 
IO$M_DATACHECK • 3-10, 3-22, 3-23, 6 
6-12, 6-13 

IO$M_DELDAT A • 3-23 
I0$M_DELETE* 1-25, 1-33 
IO$M_DMOUNT • 1-34 
I0$M _DS ABLMBX • 8-28 
IO$M_ENABLMBX • 8-37 
IO$M_ERASE* 3-20, 3-24, 6-13 
IO$M_ESCAPE • 8-8, 8-28 
IO$M_EXTEND*8-28, 8-30 
IO$M_HANGUP • 8-44 
IO$M_INCLUDE • 8-45, 8-47 
IO$M_INHEXTGAP • 6-5 
IO$M_INHRETRY • 3-23, 6-5 
I0$M_MAINT• 8-45, 8-46 
IO$M_NOECHO *8—11, 8-25, 8-28 
I0$M_N0FILTR • 8-28 
I0$M_N0F0RMAT *8-12, 8-37 
I0$M_N0RSWAIT • 7-7 
IO$M_NOW • 7-6, 7-7 
I0$M_N0WAIT*6-14, 6-16 
I0$M_0UTBAND • 8-47 
IO$M—PACKED • 2-6 
I0$M_PURGE • 8-28 
I0$M_RD_M0DEM • 8-55 
IO$M_READATTN • 7-9 
IO$M_REFRESH • 8-38 
IO$M_RE VERSE *6-12 
I0$M _SETE VF *4-10 
IO$M_SETPROT *7-11 
I0$M_SET_M0DEM • 8-45 
IO$M_TIMED*8-29 


Function modifier (cont'd.) 

I0$M _TRMNOECHO • 8-29 
IO$M_TT_ABORT • 8-47 
IO$M_TYPEAHDCNT • 8-54 
IO$M-UNLOOP *8-46 
list of • A-1 to A-9 


H 


Half-duplex mode *8-11, 8-20 
See also Duplex mode 
Hang up 

function modifier *8-44 
terminal *8-17, 8-24 
HSC50 disk controller *3-3 


4 i 


I/O function 

See also Function code 
ACP-QIO interface* 1-2 
card reader *2-5 
codes* A-1 
disk* 1-2, 3-17 
line printer *5-5 
list of • A-1 to A-9 
LPA11-K device *4-7 
magnetic tape* 1-2, 6-8 
terminal *8-27 
I/O status block 

ACP-QIO interface* 1-40 
card reader *2-11 
disk *3-27 

LAT port driver *8-56 
line printer *5-10 
LPA11-K device *4-32 
magnetic tape • 6-21 
mailbox* 7-12 
terminal *8-56 
INITIALIZE command *6-21 
Initialize command table 
LPA11-K device *4-8 
Itemlist read operations • 8-30 
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J 


JOB command 

in card reader batch job • 2-2 


K 


Keyboard control character *8-4 to 8-7, 8-10 


L 


Laboratory Peripheral Accelerator 
See LPA11-K device 
LAT port driver (LTDRIVER)*8-1 
Line printer 

carriage control • 5-6, 5-7 
character case *5-4 
character formatting • 5-2 
device characteristics • 5-3 
driver *5-1 
error recovery • 5-3 
form feed • 5-4 
function codes *5-5, A-5 
I/O functions 

IO$_SENSEMODE • 5-8 
IO$_SETCHAR • 5-9 
IO$_SETMODE • 5-9 
IO$_WRITELBLK • 5-5 
IO$_WRITEPBLK • 5-5 
IO$_WRITEVBLK • 5-5 
I/O status block • 5-10 
printall mode *5-4 
programming example *5-10 
sense mode function • 5-8 
set characteristics • 5-9 
set mode function • 5-9 
status returns • A-5 
supported devices *5-1 
SYSSGETDVI returns • 5-3 
write function • 5-5 

carriage control *5-6 
Line terminator 
terminal *8-10 
LPA11-K device 
AST 

address *4-10, 4-12 


LPA11-K device 
AST (cont'd.) 

quota *4-13 
synchronization *4-12 
buffer management • 4-14 
buffer overrun *4-10, 4-12, 4-30 
buffer queue control *4-14 
clock rate • 4-9 
data buffer *4-12 
data sampling*4-1 
data transfer command table *4-10 
data transfer start command *4-11 
data transfer stop command *4-13 
data underrun/overrun *4-10 
device characteristics • 4-4 to 4-7 
device configuration *4-1, 4-8, 4-33 
device initialization *4-3, 4-7 to 4-8, 4-31, 
4-33 

driver *4-1 

errors • 4-2 

features • 4-3 

function codes *4-7, A-4 

function modifier 

IO$M_SETEVF *4-10, 4-12 
high-level language support routines *4-13 
I/O functions 

10$_INITIALIZE • 4-8 

IO$_LOADMCODE • 4-7 
IO$_SETCLOCK • 4-9 
IO$_ST ARTDAT A *4-10 
IO$_ST ARTMPROC • 4-8 
I/O status block *4-32 
initialize command table *4-8 
initialize function *4-8 
load microcode function *4-7 
maintenance status register *4-9, 4-32 
microcode loading *4-3, 4-7, 4-31, 4-33 
modes of operation *4-1 
operator process • 4-34 
programming examples *4-35, 4-37, 4-43 
RSX-11M/M-PLUS and VMS differences* 
4-34 

set clock function • 4-9 
start data transfer request function *4-10 
start microprocessor function • 4-8 
status returns *4-8, 4-9, 4-10, 4-12, 4-32, 
A-5 

stop command *4-13 
subroutines 

argument usage • 4-15 to 4-17 
list *4-13 

supported device *4-1 
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LPA11-K device (cont'd.) 
supporting software *4-3 
SYS$CANCEL *4-13 
SYS$GETDVI returns • 4-4 
timeout error *4-2 


M 


Magnetic tape 

ACP control function* 1-34, 6-10 
ACP create file operation* 1-28 
available function • 6-21 
BOT marker *6-14, 6-15 
byte count 
read *6-12 
write *6-14 

data check *6-4, 6-12, 6-13 
data security erase function *6-21 
density *6-19 

device characteristics *6-6 to 6-8 
driver *6-1 

end-of-volume detection *6-15 

EOF status *6-12 

EOT 

marker • 6-14 to 6-16 
status *6-12, 6-14, 6-16 
error recovery • 6-5 
extended characteristics *6-8 
features • 6-3 
file attributes • 6-4 
function codes *6-8, A-6 
function modifiers 

IO$M_DATACHECK • 6-4, 6-12, 6-13 
IO$M_ERASE *6-13 
IO$M_INHEXTGAP • 6-5 
IO$M_INHRETRY *6-5 
IO$M_NOWAIT*6-14, 6-16 
IO$M_REVERSE *6-12 
I/O functions • 6-8 

See also ACP-QIO interface 
arguments *6-10 
IO$_ACCESS • 6-9 
IO$_ACPCONTROL • 1-36, 6-10 
IO$_AVAILABLE • 6-21 
IO$_CRE ATE • 6-9 
IO$_DE ACCESS • 6-9 
IO$_DSE*6-9, 6-21 
IO$_MODIFY • 6-9 
IO$_PACKACK • 6-21 


Magnetic tape 

I/O functions (cont'd.) 

IO$_RE ADLBLK *6-12 
IO$_RE ADPBLK *6-12 
IO$_RE ADVBLK *6-12 
IO$_REWIND *6-14 
IO$_RE WINDOFF *6-16 
IO$_SENSEMODE *6-16 
IO$_SETCH AR *6-17 
IO$_SETMODE *6-17 
IO$_SKIPFILE *6-14 
IO$_SKIPRECORD *6-15 
IO$_UNLOAD *6-16 
IO$_WRITELBLK *6-13 
IO$_WRITEOF *6-16 
IO$_WRITEPBLK *6-13 
IO$_WRITE VBLK *6-13 
I/O status block *6-21 
master adapters • 6-4 
pack acknowledge function • 6-21 
parity *6-19 
positioning* 1-36 
programming example *6-22 
quotas *6-8 
read function *6-12 
read reverse function *6-12, 6-13 
rewind function *6-14 
rewind offline function *6-16 
sense mode function *6-16 
set characteristics function *6-17 
set mode function *6-17 
characteristics *6-19 
skip file function *6-14 
skip record function *6-15 
slave formatter • 6-4 
status returns *A-7 
streaming tape systems *6-5 
supported devices *6-1 
SYS$GETDVI returns *6-6 
tape controllers • 6-2 
tape mark *6-12,6-14, 6-15 
thrashing *6-6 
TMSCP magnetic tapes *6-1 
TU58 magnetic tape 
See Disk, TU58 
unload function *6-16 
write end-of-file function *6-16 
write function *6-13 
Mailbox 

See also Terminal 
creating *7-1 


Index-7 






Index 


Mailbox (cont'd.) 
deleting *7-2 

device characteristics • 7-4 
disable terminal*8-21 
driver *7-1 

function codes *7-5, A-7 
function modifiers 

IO$M_NORSWAIT • 7-7 
IO$M_NOW* 7-2, 7-6, 7-7, 7-8, 7-9 
IO$M_READATTN • 7-9 
IO$M_SETPROT *7-11 
I/O functions 

IO$_RE ADLBLK • 7-6 
IO$_RE ADPBLK • 7-6 
IO$_RE ADVBLK • 7-6 
IO$_WRITELBLK • 7-7 
IO$_WRITEOF • 7-8 
IO$_WRITEPBLK • 7-7 
IO$_WRITEVBLK • 7-7 
I/O status block *7-12 
list of operations *7-1 
message format • 7-3 
terminal *8-18 
message size *7-2 
multiport memory *7-1 
permanent *7-2, 7-3 
programming example *7-13 
protection *7-2, 7-3, 7-11 
read attention AST function • 7-9 
read function • 7-6 
set attention AST function • 7-9 
set protection function *7-11 
status returns • A-7 
SYSSGETDVI returns *7-4 
temporary *7-2, 7-3, 7-4 
terminal/mailbox interaction *8-17 
volume protection *7-11 
write attention AST function • 7-9 
write end-of-file message function • 7-8 
write function • 7-7 
Master adapter *6-4 
Message format 
See Mailbox 
Mode card 

026 punch mode *2-2 
029 punch mode *2-2 
Modify file function* 1-32 
MOUNT command *6-21 
Mount function* 1-34 
Multinational character set 

See DEC Multinational Character Set 


Multiplexer 

DMB32 device *8-1 
DMF32 device *8-1 
DZ11 device *8-1 
DZ32 device *8-2 


o 


Out-of-band AST*8-12, 8-47 


P 


Parity flag • 8-43 
Passall mode *5-4 
PASSWORD command 

in card reader batch job *2-2 
Pasthru mode*8-10, 8-12, 8-25,8-28 
Permanent mailbox 
See Mailbox 
Port access mode • 3-8 
Port selection • 3-8 
Printer 

See Line printer 
Protection 

See also Mailbox 
directory entry* 1-11 


Q 


Quota 

AST*3-18, 4-13, 6-8,7-5,7-9,8-44 
buffered 1/0*3-18, 6-8, 7-5 
BVTELIM* 1 — 12 
direct 1/0*3-18, 6-8 
disk* 1-37 to 1-39 
mailbox buffer *7-2, 7-3, 7-5 
Quota file transfer block* 1-38 


R 


Read attention AST function • 7-9 
Read/write attributes subfunction* 1-17 
Record attributes value* 1-22 
RETURN key*8-7 
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Rewind offline function®6-16 
RSX-11M/M-PLUS 

differences from VMS *4-34 
RX01 console disk®3-6 


s 


Sector translation • 3-12 
Seek operation *3-11 
Sense tape mode function *6-16 
Serial line multiplexer *8-1 
Set attention AST 
See Attention AST 
SET CARD-READER command • 2-2 
Set characteristic 
card reader *2-7 
line printer *5-9 
magnetic tape • 6-17 
terminal • 8-40 
Set mode 

card reader *2-7 
line printer*5-9 
magnetic tape *6-17 
mailbox *7-9 
terminal • 8-40 

SET TERMINAL command *8-4, 8-18, 8-26 

Set translation mode • 2-2 

Skip file function *6-14 

Skip sectoring • 3-12 

Slave formatter *6-4 

SS$_ABORT • 8-46, 8-51, A-2, A-3, A-5, 
A-7, A-9 

SS$_ ACCONFLICT • A-1 
SS$_ACCVIO *7-12, 8-52 
SS$_ACPV AFUL • A-1 
SS$_B AD ATTRIB • A-1 
SS$_B ADCHKSUM • A-1 
SS$_BADESCAPE • 8-8, A-9 
SS$_BADFILEHDR • A-1 
SS$_BADFILEN AME • A-1 
SS$_B ADFILE VER • A-1 
SS$_B ADIRECTORY • A-1 
SS$_BADPARAM • 8-52, A-1, A-5, A-9 
SS$_B ADQFILE • A-1 
SS$_BLOCKCNTERR • A-1 
SS$_BUFFEROVF • 7-6, A-7 
SS$_BUFNOT ALIGN • A-5 
SS$_CANCEL* A-3, A-5, A-7, A-9 
SS$_CONTROLC • 8-47, A-9 


SS$_CONTROLO • A-9 
SS$_CONTROLY • A-9 
SS$_CRE ATED • A-1 
SS$_CTRLERR* A-3, A-5, A-7 
SS$_DATACHECK • A-3, A-5, A-7 
SS$_DATAOVERUN *8-10, A-2, A-3, A-7, 
A-9 

SS$_DEVACTIVE • 8-51, A-5 
SS$_DEVCMDERR • A-5 
SS$_DE VICEFULL • A-1 
SS$_DE VOFFLINE • A-7 
SS$_DEVREQERR • A-5 
SS$_DIRFULL • A-1 
SS$_DIRNOTEMPTY • A-1 
SS$_DRVERR • A-3, A-7 
SS$_DUPDSKQUOT A • A-1 
SS$_DUPFILENAME • A-1 
SS$_ENDOFFILE *6-15, 7-6, 7-8, A-1, A-2, 
A-7 

SS$_ENDOFT APE•A-7 
SS$_ENDOFVOLUME *6-15, A-7 
SS$_EXB YTLM • A-1 
SS$_EXDISKQUOT A • A-1 
SS$_EXQUOT A • A-5 
SS$_FCPRE ADERR • A-1 
SS$_FCPRE WNDERR • A-1 
SS$_FCPSP ACERR • A-1 
SS$_FCPWRITERR • A-1 
SS$_FILELOCKED • A-1 
SS$_FILENUMCHK • A-1 
SS$_FILEPURGED • A-1 
SS$_FILESEQCHK • A-1 
SS$_FILESTRUCT • A-1 
SS$_FILNOTEXP • A-1 
SSS—FORCEDERR • A-3 
SS$_FORMAT • A-3, A-7 
SS$_H ANGUP *8-12 
SS$_HE ADERFULL • A-1 
SS$_IBCERROR • A-1 
SS$_IDXFILEFULL • A-1 
SS$_ILLCNTRFUNC • A-1 
SS$_ILLIOFUNC • 8—51, A-3, A-7 
SS$_INCOMPAT • A-9 
SS$_INSFBUFDP • A-5 
SS$_INSFM APREQ • A-5 
SS$_INSFMEM *7-12, A-5 
SS$_IVADDR • A-3 
SS$_IVBUFLEN • A-3, A-5 
SS$_IVMODE • A-5 
SS$_MBFULL*7-2, 7-7, 7-12 
SS$_MBT OOSML *7-12 
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SS$_MCNOTV ALID • A-5 
SS$_MEDOFL • A-3, A-7 
SS$_NODISKQUOT A • A-1 
SS$_NOMOREFILES • A-1 
SS$_NONEXDRV • A-3, A-7 
SS$_NOPRIV • 7-11, 7-12, 8-52, A-2 
SS$_NOQFILE • A-2 

SS$_NORMAL• 8-51, 8-52, A-2, A-3, A-7, 
A-9 

SS$_NOSUCHFILE • A-2 
SS$_NOT APEOP • A-2 
SS$_NOTLABELMT • A-2 
SS$_NOTPRINTED • A-2 
SS$_NOTVOLSET • A-2 
SS$_OPINCOMPL» A-3, A-7 
SS$_OVRDSKQUOT A • A-2 
SS$_PARITY» A-3, A-5, A-7, A-9 
SS$_PARTESCAPE • 8-8, 8-32, A-9 
SS$_POWERF AIL • A-5 
SS$_QF ACTIVE • A-2 
SS$_QFNOT ACT • A-2 
SS$_RCT • A-3 
SS$_RDDELD AT A • A-3 
SS$_SUPERSEDE • A-2 
SS$_T APEPOSLOST • A-2 
SS$_TIMEOUT *8-29, 8-51, A-3, A-5, A-7, 
A-9 

SS$_TOOM ANYVER • A-2 
SS$_UNSAFE • A-3, A-7 
SS$_VOLINV • A-3, A-7 
SSS—WASECC • A-3 
SS$_WRITLCK»A-2, A-3, A-7 
SS$_WRONG ACP • A-2 
SYSSASSIGN*7-2, 8-17, 8-53 
SYS$CANCEL»4-13 
SYS$CREMBX*7-1 
SYS$DASSGN•7-2 
SYS$DELMBX•7-2 
SYS$DISMOUNT • 1-36 
SYS$GETDVI • 6-6 
card reader • 2-5 
disk* 3-16 
line printer*5-3 
LPA11-K device *4-4 
mailbox* 7-4 
terminal *8-19 

System console terminal *8-1 


T 


Tab 

CTRL/I *8-7 

terminal mechanical *8-21 
terminal tab stops *8-37 
Tape 

See Magnetic tape 
Tape mark*6-12, 6-14, 6-15 
Temporary mailbox *7-3 
Terminal 

ANSI CRT terminal *8-22 
autobaud detection *8-18, 8-23 
baud rate *8-18, 8-23, 8-42 
bell (CTRL/G) • 8-9 

broadcast message *8-17, 8-21, 8-23, 8-48 

carriage control *8-38 

characteristic 

See Terminal characteristic 
command line editing *8-3, 8-36 
command recall (CTRL/B)*8-3, 8-6 
control and data signals *8-15 
control characters• 8-4 to 8-7, 8-10, 8-28 
numeric values *B-1 
control sequences *8-9 
cursor movement *8-3, 8-6, 8-22 
delete character *8-3 
delete line (CTRL/U)*8-5, 8-28 
device characteristics *8-19, 8-20 
categories • 8-26 
changing • 8-43 
extended • 8-22 
dial-up 

characteristic • 8-22 
lines *8-12, 8-24, 8-44 
support *8-12 

DIGITAL CRT terminal *8-23, 8-24 
discard output (CTRL/O) *8-5, 8-28, 8-37 
driver *8-1 

duplex modes *8-11, 8-12 
enable CTRL/C AST *8-44 
enable CTRL/Y AST *8-44 
escape sequences *8-8, 8-58 
ANSI*B-9 

DIGIT AL-private • B-9 
overflow size (item code) • 8-32 
extended characteristics *8-22 
fallback conversion *8-12, 8-24, 8-44 
features • 8-2 
form feed • 8-21, 8-37 
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Terminal (cont'd.) 
frame size • 8-43 
function codes *8-27, A-8 
function modifiers 

See also Terminal, item codes 
IO$M_BRDCST •8-49, 8-56 
IO$M_BREAKTHRU • 8-11, 8-37 
IO$M_CANCTRLO • 8-5, 8-37 
IO$M_CTRLCAST • 8-44 
IO$M_CTRLYAST *8-6, 8-12, 8-44 
IO$M_CVTLOW • 8-28 
IO$M_DSABLMBX • 8-28 
IO$M_ENABLMBX • 8-37 
IO$M_ESCAPE • 8-8, 8-28 
IO$M_EXTEND • 8-28, 8-30 
IO$M_HANGUP • 8-44 
IO$M_INCLUDE • 8-19, 8-45, 8-47 
I0$M_L00P • 8-46 
I0$M_LT_C0NNECT • 8-50 
I0$M_LT_DISC0N • 8-50 
I0$M_LT_MAP_P0RT • 8-50 
PI parameters*8-51 
IO$M_LT_RATING • 8-50 
I0$M_MAINT*8-45, 8-46 
I0$M_N0ECH0 *8-10, 8-11, 8-25, 8-28 
I0$M_N0FILTR • 8-28 
I0$M_N0F0RMAT*8-12, 8-37, 8-46 
I0$M_0UTBAND • 8-47 
I0$M_PURGE • 8-28 
I0$M_RD_M0DEM • 8-55 
I0$M—REFRESH • 8-38 
I0$M_SET_M0DEM • 8-45 
I0$M_TIMED • 8-29 
I0$M_TRMNOECHO • 8-29 
I0$M—TT_ABORT *8-19, 8-47 
IO$M_TYPEAHDCNT • 8-54 
IO$M_UNLOOP • 8-46 
hang up *8-12, 8-16, 8-17, 8-24, 8-44, 
8-53 

I/O functions 

I0$_READLBLK • 8-27 
IO$_READPROMPT *8-27, 8-28 
IO$_READVBLK • 8-27 
IO$_SENSECHAR • 8-53 
IO$_SENSEMODE • 8-53 
IO$_SETCHAR • 8-40 
IOS—SETMODE • 8-40 
IO$_TTY—PORT • 8-50 
IO$_WRITELBLK • 8-37 
IO$_WRITEPBLK • 8-37 
IO$_WRITEVBLK • 8-37 


Terminal (cont'd.) 

I/O status block *8-56 
initiate login *8-10 
input processing • 8-3 
insert/overstrike (CTRL/A)*8-3, 8-7 
interrupt (CTRL/Y)*8-6 
item codes • 8-31 to 8-35 
itemlist read • 8-30 
example *8-69 
item codes • 8-31 to 8-35 
item descriptor *8-31 
LAT line *8-1 
LAT port driver *8-49 

application services creation • 8-52 
example *8-72 
I/O functions *8-50 
LAT rejection codes *8-59 
line editing *8-3, 8-24 

See also Terminal, item codes 
line feed *8-37 
line terminators *8-10 
mailbox *8-17, 8-37 

message format *8-18 
message types *8-17 
modem 

characteristic *8-21 
control signals *8-15 
data signals *8-15 
protocol *8-13 
sense signals *8-55 
signal control *8-12 
no type-ahead • 8-21 
out-of-band 

See also Out-of-band AST 
characters *8-19 
output formatting *8-12, 8-26 
output processing *8-11 
page length and width *8-42, 8-54 
parity flag • 8-43 

pasthru mode*8-10, 8-12, 8-25,8-28 
process preservation *8-16 
programming examples*8-59 
protocol *8-13 
read function *8-27 
arguments *8-27 
function modifiers • 8-28 
itemlist read • 8-30 
terminating *8-27 
terminators *8-29 
with timeout *8-27, 8-29 
read verify *8-7, 8-35 
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Terminal 

read verify (cont'd.) 

example *8-69 
receive speed • 8-42 
redisplay data (CTRL/R) • 8-7, 8-28 
ReGIS graphics *8-25 
restart data (CTRL/Q) • 8-7 
sense characteristics function • 8-53 
sense mode function • 8-53 
serial line multiplexer*8-1 
set characteristics function • 8-40 
arguments *8-41 
set mode function • 8-40 
arguments *8-41 

SET TERMINAL DCL command *8-4, 8-18, 
8-26 

SIXEL graphics *8-25 
special operating modes *8-10 
status (CTRL/T) • 8-7 
status returns* A-9 
stop data (CTRL/S) • 8-7 
supported devices *8-1 
SYSSGETDVI returns *8-19 
system password • 8-25 
tab 

CTRL/I *8-7 
mechanical *8-21 
stops *8-37 

terminator mask *8-29, 8-30 
time (CTRL/T) *8-7 
transmit speed • 8-42 

TTY_DIALTYPE SYSGEN parameter*8-12, 
8-13, 8-16 

type-ahead *8-9, 8-17, 8-20,8-54 
alternate buffer • 8-22 
unsolicited data *8-17 
write breakthrough function • 8-38 
write function • 8-37 

carriage control *8-38 
function modifiers *8-37 
XON/XOFF control *8-25 
Terminal characteristic 
ANSI CRT *8-22 
ASCII (8-bit) code *8-20 
baud rate *8-23 
block mode *8-23 
dial-up line *8-24 
dial-up terminal *8-22 
DIGITAL CRT *8-23, 8-24 
DMA mode *8-24 
edit *8-24 

extended characteristics *8-22 



Terminal characteristic (cont'd.) 
local echo *8-25 
modem *8-21 
modify hang up *8-25 
no echo • 8-21 
no type ahead *8-21 
pasthru mode *8-25 
ReGIS graphics *8-25 
remote terminal • 8-22 
secure *8-25 
set speed • 8-25 
SIXEL graphics *8-25 
system password *8-25 
XON/XOFF *8-25 

Terminator character bit mask *8-29 
Thrashing 

magnetic tape • 6-6 
Translation 

logical to physical *3-12 
Translation mode card 
026 punch mode *2-2 
029 punch mode *2-2 
Truncate subfunction* 1-15 
TU58 magnetic tape 
See Disk 
Type-ahead 

See Terminal, type-ahead 





UDA50 disk adapter *3-2 
Unload function 
disk *3-25 
magnetic tape *6-16 



Write attention AST function *7-9 
Write breakthrough function • 8-38 
Write end-of-file function 
magnetic tape *6-16 
message *7-8 



XQP (extended QIO processor)* 1-1 
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